参考

• 1: 词汇表
• 2: API 概述
• 2.1: Kubernetes API 概念
• 2.2: 服务器端应用（Server-Side Apply）
• 2.3: 客户端库
• 2.4: Kubernetes 弃用策略
• 2.5: Kubernetes API 健康端点
• 3: 常见的标签、注解和污点
• 4: 访问 API
• 4.1: 用户认证
• 4.2: 使用启动引导令牌（Bootstrap Tokens）认证
• 4.3: 证书签名请求
• 4.4: 使用准入控制器
• 4.5: 动态准入控制
• 4.6: 管理服务账号
• 4.7: 鉴权概述
• 4.8: 使用 RBAC 鉴权
• 4.9: 使用 Node 鉴权
• 4.10: Webhook 模式
• 4.11: 使用 ABAC 鉴权
• 5: Kubernetes API
• 6: Kubernetes 问题和安全
• 6.1: Kubernetes 问题追踪
• 6.2: Kubernetes 安全和信息披露
• 7: 安装工具
• 7.1: Kubeadm
• 7.1.1: 创建 Kubeadm
• 7.1.1.1:
• 7.1.1.2:
• 7.1.1.3:
• 7.1.1.4:
• 7.1.1.5:
• 7.1.1.6:
• 7.1.1.7:
• 7.1.1.8:
• 7.1.1.9:
• 7.1.1.10:
• 7.1.1.11:
• 7.1.1.12:
• 7.1.1.13:
• 7.1.1.14:
• 7.1.1.15:
• 7.1.1.16:
• 7.1.1.17:
• 7.1.1.18:
• 7.1.1.19:
• 7.1.1.20:
• 7.1.1.21:
• 7.1.1.22:
• 7.1.1.23:
• 7.1.1.24:
• 7.1.1.25:
• 7.1.1.26:
• 7.1.1.27:
• 7.1.1.28:
• 7.1.1.29:
• 7.1.1.30:
• 7.1.1.31:
• 7.1.1.32:
• 7.1.1.33:
• 7.1.1.34:
• 7.1.1.35:
• 7.1.1.36:
• 7.1.1.37:
• 7.1.1.38:
• 7.1.1.39:
• 7.1.1.40:
• 7.1.1.41:
• 7.1.1.42:
• 7.1.1.43:
• 7.1.1.44:
• 7.1.1.45:
• 7.1.1.46:
• 7.1.1.47:
• 7.1.1.48:
• 7.1.1.49:
• 7.1.1.50:
• 7.1.1.51:
• 7.1.1.52:
• 7.1.1.53:
• 7.1.1.54:
• 7.1.1.55:
• 7.1.1.56:
• 7.1.1.57:
• 7.1.1.58:
• 7.1.1.59:
• 7.1.1.60:
• 7.1.1.61:
• 7.1.1.62:
• 7.1.1.63:
• 7.1.1.64:
• 7.1.1.65:
• 7.1.1.66:
• 7.1.1.67:
• 7.1.1.68:
• 7.1.1.69:
• 7.1.1.70:
• 7.1.1.71:
• 7.1.1.72:
• 7.1.1.73:
• 7.1.1.74:
• 7.1.1.75:
• 7.1.1.76:
• 7.1.1.77:
• 7.1.1.78:
• 7.1.1.79:
• 7.1.1.80:
• 7.1.1.81:
• 7.1.1.82:
• 7.1.1.83:
• 7.1.1.84:
• 7.1.1.85:
• 7.1.1.86:
• 7.1.1.87:
• 7.1.1.88:
• 7.1.1.89:
• 7.1.1.90:
• 7.1.1.91:
• 7.1.1.92:
• 7.1.1.93:
• 7.1.1.94:
• 7.1.1.95:
• 7.1.1.96:
• 7.1.1.97:
• 7.1.1.98:
• 7.1.1.99:
• 7.1.1.100:
• 7.1.1.101:
• 7.1.1.102:
• 7.1.1.103:
• 7.1.1.104:
• 7.1.1.105:
• 7.1.1.106:
• 7.1.1.107:
• 7.1.1.108:
• 7.1.1.109:
• 7.1.1.110:
• 7.1.2: kubeadm init
• 7.1.3: kubeadm join
• 7.1.4: kubeadm upgrade
• 7.1.5: kubeadm config
• 7.1.6: kubeadm reset
• 7.1.7: kubeadm token
• 7.1.8: kubeadm version
• 7.1.9: kubeadm alpha
• 7.1.10: kubeadm certs
• 7.1.11: kubeadm init phase
• 7.1.12: kubeadm join phase
• 7.1.13: kubeadm reset phase
• 7.1.14: kubeadm upgrade phase
• 7.1.15: 实现细节
• 8: kubectl
• 8.1: kubectl 概述
• 8.2: JSONPath 支持
• 8.3: kubectl
• 8.4: kubectl 命令
• 8.5: kubectl 备忘单
• 8.6: kubectl 的用法约定
• 8.7: 适用于 Docker 用户的 kubectl
• 9: 组件工具
• 9.1: 特性门控
• 9.2: kubelet
• 9.3: kube-apiserver
• 9.4: kube-controller-manager
• 9.5: kube-proxy
• 9.6: kube-scheduler
• 9.7: Kubelet 认证/鉴权
• 9.8: TLS 启动引导
• 10: 配置 API
• 10.1: Client Authentication (v1beta1)
• 10.2: kube-apiserver Audit Configuration (v1)
• 10.3: kube-proxy Configuration (v1alpha1)
• 10.4: kube-scheduler Configuration (v1beta1)
• 10.5: kube-scheduler Policy Configuration (v1)
• 10.6: Kubelet Configuration (v1beta1)
• 10.7: WebhookAdmission Configuration (v1)
• 11: 调度
• 11.1: 调度策略
• 11.2: 调度器配置
• 12: 其他工具

1 - 词汇表

2 - API 概述

本文提供了 Kubernetes API 的参考信息。

REST API 是 Kubernetes 的基本结构。 所有操作和组件之间的通信及外部用户命令都是调用 API 服务器处理的 REST API。 因此，Kubernetes 平台视一切皆为 API 对象， 且它们在 API 中有相应的定义。

Kubernetes API 参考列 出了 Kubernetes v1.22 版本的 API。

如需了解一般背景信息，请查阅 Kubernetes API。 Kubernetes API 控制访问描述了客户端如何 向 Kubernetes API 服务器进行身份认证以及他们的请求如何被鉴权。

API 版本控制

JSON 和 Protobuf 序列化模式遵循相同的模式更改原则。 以下描述涵盖了这两种格式。

API 版本控制和软件版本控制是间接相关的。 API 和发布版本控制提案 描述了 API 版本控制和软件版本控制间的关系。

不同的 API 版本代表着不同的稳定性和支持级别。 你可以在 API 变更文档 中查看到更多的不同级别的判定标准。

下面是每个级别的摘要：

• Alpha:
  • 版本名称包含 alpha（例如，v1alpha1）。
  • 软件可能会有 Bug。启用某个特性可能会暴露出 Bug。 某些特性可能默认禁用。
  • 对某个特性的支持可能会随时被删除，恕不另行通知。
  • API 可能在以后的软件版本中以不兼容的方式更改，恕不另行通知。
  • 由于缺陷风险增加和缺乏长期支持，建议该软件仅用于短期测试集群。

• Beta:

  • 版本名称包含 beta （例如， v2beta3）。
  • 软件被很好的测试过。启用某个特性被认为是安全的。 特性默认开启。
  • 尽管一些特性会发生细节上的变化，但它们将会被长期支持。
  • 在随后的 Beta 版或稳定版中，对象的模式和（或）语义可能以不兼容的方式改变。 当这种情况发生时，将提供迁移说明。 模式更改可能需要删除、编辑和重建 API 对象。 编辑过程可能并不简单。 对于依赖此功能的应用程序，可能需要停机迁移。
  • 该版本的软件不建议生产使用。 后续发布版本可能会有不兼容的变动。 如果你有多个集群可以独立升级，可以放宽这一限制。

  说明： 请试用测试版特性时并提供反馈。特性完成 Beta 阶段测试后， 就可能不会有太多的变更了。

• Stable:
  • 版本名称如 vX，其中 X 为整数。
  • 特性的稳定版本会出现在后续很多版本的发布软件中。

API 组

API 组 能够简化对 Kubernetes API 的扩展。 API 组信息出现在REST 路径中，也出现在序列化对象的 apiVersion 字段中。

以下是 Kubernetes 中的几个组：

• 核心（也叫 legacy）组的 REST 路径为 /api/v1。 核心组并不作为 apiVersion 字段的一部分，例如， apiVersion: v1。
• 指定的组位于 REST 路径 /apis/$GROUP_NAME/$VERSION， 并且使用 apiVersion: $GROUP_NAME/$VERSION （例如， apiVersion: batch/v1）。 你可以在 Kubernetes API 参考文档 中查看全部的 API 组。

启用或禁用 API 组

资源和 API 组是在默认情况下被启用的。 你可以通过在 API 服务器上设置 --runtime-config 参数来启用或禁用它们。 --runtime-config 参数接受逗号分隔的 <key>[=<value>] 对， 来描述 API 服务器的运行时配置。如果省略了 =<value> 部分，那么视其指定为 =true。 例如：

• 禁用 batch/v1， 对应参数设置 --runtime-config=batch/v1=false
• 启用 batch/v2alpha1， 对应参数设置 --runtime-config=batch/v2alpha1

说明： 启用或禁用组或资源时， 你需要重启 API 服务器和控制器管理器来使 --runtime-config 生效。

持久化

Kubernetes 通过 API 资源来将序列化的状态写到 etcd 中存储。

接下来

• 进一步了解 API 惯例
• 阅读 聚合器

2.1 - Kubernetes API 概念

本页描述 Kubernetes API 的通用概念。

Kubernetes API 是基于资源的（RESTful）、通过 HTTP 提供的编程接口。 API 支持通过标准的 HTTP 动词（POST、PUT、PATCH、DELETE 和 GET） 检视、创建、更新和删除主要资源，为很多允许细粒度权限控制的对象提供子资源 （如将 Pod 绑定到节点上），并且出于便利性或效率考虑，支持并提供这些资源的 不同表示形式。 Kubernetes API 还通过 "watch" 和一致性的列表支持高效的资源变更通知， 从而允许其他组件对资源的状态进行高效的缓存和同步。

标准 API 术语

大多数 Kubernetes API 资源类型都是 对象： 它们代表的是集群中某一概念的具体实例，例如一个 Pod 或名字空间。 为数不多的几个 API 资源类型是“虚拟的” - 它们通常代表的是操作而非对象本身， 例如访问权限检查（使用 POST 请求发送一个 JSON 编码的 SubjectAccessReview 负载到 subjectaccessreviews 资源）。 所有对象都有一个唯一的名字，以便支持幂等的创建和检视操作，不过如果虚拟资源类型 不可检视或者不要求幂等，可以不具有唯一的名字。

Kubernetes 一般会利用标准的 RESTful 术语来描述 API 概念：

• 资源类型（Resource Type） 是在 URL 中使用的名称（pods、namespaces、services）
• 所有资源类型都有具有一个 JSON 形式（其对象的模式定义）的具体表示，称作类别（Kind）
• 某资源类型的实例的列表称作 集合（Collection）
• 资源类型的单个实例被称作 资源（Resource）

所有资源类型要么是集群作用域的（/apis/GROUP/VERSION/*），要么是名字空间 作用域的（/apis/GROUP/VERSION/namespaces/NAMESPACE/*）。 名字空间作用域的资源类型会在其名字空间被删除时也被删除，并且对该资源类型的 访问是由定义在名字空间域中的授权检查来控制的。 下列路径用来检视集合和资源：

• 集群作用域的资源：
  • GET /apis/GROUP/VERSION/RESOURCETYPE - 返回指定资源类型的资源的集合
  • GET /apis/GROUP/VERSION/RESOURCETYPE/NAME - 返回指定资源类型下名称为 NAME 的资源
• 名字空间作用域的资源：
  • GET /apis/GROUP/VERSION/RESOURCETYPE - 返回所有名字空间中指定资源类型的全部实例的集合
  • GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE - 返回名字空间 NAMESPACE 内给定资源类型的全部实例的集合
  • GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME - 返回名字空间 NAMESPACE 中给定资源类型的名称为 NAME 的实例

由于名字空间本身是一个集群作用域的资源类型，你可以通过 GET /api/v1/namespaces/ 检视所有名字空间的列表，使用 GET /api/v1/namespaces/NAME 查看特定名字空间的 详细信息。

几乎所有对象资源类型都支持标准的 HTTP 动词 - GET、POST、PUT、PATCH 和 DELETE。 Kubernetes 使用术语 list 来描述返回资源集合的操作，以便与返回单个资源的、 通常称作 get 的操作相区分。

某些资源类型有一个或多个子资源（Sub-resource），表现为对应资源下面的子路径：

• 集群作用域的子资源：GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCE
• 名字空间作用域的子资源：GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCE

取决于对象是什么，每个子资源所支持的动词有所不同 - 参见 API 文档以了解更多信息。 跨多个资源来访问其子资源是不可能的 - 如果需要这一能力，则通常意味着需要一种 新的虚拟资源类型了。

高效检测变更

为了使客户端能够构造一个模型来表达集群的当前状态，所有 Kubernetes 对象资源类型 都需要支持一致的列表和一个称作 watch 的增量变更通知信源（feed）。 每个 Kubernetes 对象都有一个 resourceVersion 字段，代表该资源在下层数据库中 存储的版本。检视资源集合（名字空间作用域或集群作用域）时，服务器返回的响应 中会包含 resourceVersion 值，可用来向服务器发起 watch 请求。 服务器会返回所提供的 resourceVersion 之后发生的所有变更（创建、删除和更新）。 这使得客户端能够取回当前的状态并监视其变更，且不会错过任何变更事件。 客户端的监视连接被断开时，可以从最后返回的 resourceVersion 重启新的监视连接， 或者执行一个新的集合请求之后从头开始监视操作。 参阅资源版本语义以了解更多细节。

例如：

1. 列举给定名字空间中的所有 Pods：

   GET /api/v1/namespaces/test/pods
   ---
   200 OK
   Content-Type: application/json
   {
     "kind": "PodList",
     "apiVersion": "v1",
     "metadata": {"resourceVersion":"10245"},
     "items": [...]
   }
   

2. 从资源版本 10245 开始，以 JSON 对象的形式接收所有创建、删除或更新操作的通知：

   GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
   ---
   200 OK
   Transfer-Encoding: chunked
   Content-Type: application/json
   
   {
     "type": "ADDED",
     "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
   }
   {
     "type": "MODIFIED",
     "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "11020", ...}, ...}
   }
   ...
   

给定的 Kubernetes 服务器只会保留一定的时间内发生的历史变更列表。 使用 etcd3 的集群默认保存过去 5 分钟内发生的变更。 当所请求的 watch 操作因为资源的历史版本不存在而失败，客户端必须能够处理 因此而返回的状态代码 410 Gone，清空其本地的缓存，重新执行 list 操作， 并基于新的 list 操作所返回的 resourceVersion 来开始新的 watch 操作。 大多数客户端库都能够提供某种形式的、包含此逻辑的工具。 （在 Go 语言客户端库中，这一设施称作 Reflector，位于 k8s.io/client-go/cache 包中。)

监视书签

为了处理历史窗口过短的问题，我们引入了 bookmark（书签） 监视事件的概念。 该事件是一种特殊事件，用来标示客户端所请求的、指定的 resourceVersion 之前 的所有变更都以被发送。该事件中返回的对象是所请求的资源类型，但其中仅包含 resourceVersion 字段，例如：

GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
  "type": "ADDED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
}
...
{
  "type": "BOOKMARK",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
}

通过在 watch 请求中设置 allowWatchBookmarks=true 选项，可以请求 bookmark 事件，但是客户端不能假定服务器端会按某特定时间间隔返回书签事件，甚至也不能 假定服务器一定会发送 bookmark 事件。

分块检视大体量结果

在较大规模的集群中，检视某些资源类型的集合时可能会返回较大体量的响应数据，对 服务器和客户端都会造成影响。例如，某集群可能包含数万个 Pod，每个 Pod 的 JSON 编码都有 1-2 KB 的大小。返回所有名字空间的全部 Pod 时，其结果可能体量很大 （10-20 MB）且耗用大量的服务器资源。 从 Kubernetes 1.9 开始，服务器支持将单一的大体量集合请求分解成多个小数据块 同时还保证整个请求的一致性的能力。 各个数据块可以按顺序返回，进而降低请求的尺寸，允许面向用户的客户端以增量形式 呈现返回结果，改进系统响应效果。

为了用分块的形式返回一个列表，集合请求上可以设置两个新的参数 limit 和 continue，并且所有 list 操作的返回结果列表的 metadata 字段中会包含一个 新的 continue 字段。 客户端应该将 limit 设置为希望在每个数据块中收到的结果个数上限，而服务器则 会在结果中至多返回 limit 个资源并在集合中还有更多资源的时候包含一个 continue 值。客户端在下次请求时则可以将此 continue 值传递给服务器， 告知后者要从何处开始返回结果的下一个数据块。 通过重复这一操作直到服务器端返回空的 continue 值，客户端可以受到结果的 全集。

与 watch 操作类似，continue 令牌也会在很短的时间（默认为 5 分钟）内过期， 并在无法返回更多结果时返回 410 Gone 代码。 这时，客户端需要从头开始执行上述检视操作或者忽略 limit 参数。

例如，如果集群上有 1253 个 Pods，客户端希望每次收到包含至多 500 个 Pod 的 数据块，它应按下面的步骤来请求数据块：

1. 列举集群中所有 Pod，每次接收至多 500 个 Pods：

GET /api/v1/pods?limit=500
---
200 OK
Content-Type: application/json

{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "ENCODED_CONTINUE_TOKEN",
    ...
  },
  "items": [...] // returns pods 1-500
}

2. 继续前面的调用，返回下一组 500 个 Pods：

GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
---
200 OK
Content-Type: application/json

{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "ENCODED_CONTINUE_TOKEN_2",
    ...
  },
  "items": [...] // returns pods 501-1000
}

3. 继续前面的调用，返回最后 253 个 Pods：

GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
---
200 OK
Content-Type: application/json

{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "", // continue token is empty because we have reached the end of the list
    ...
  },
  "items": [...] // returns pods 1001-1253
}

注意 list 操作的 resourceVersion 在每个请求中都设置的是同一个数值， 这表明服务器要向我们展示一个一致的 Pods 快照视图。 在版本 10245 之后创建、更新或删除的 Pods 都不会显示出来，除非用户发出 list 请求时不指定 continue 令牌。 这一设计使得客户端能够将较大的响应切分为较小的数据块，且能够对较大的集合 执行监视动作而不会错失任何更新事件。

以表格形式接收资源

kubectl get 命令的输出是一个包含一个或多个资源的简单表格形式。 过去，客户端需要重复 kubectl 中所实现的表格输出和描述输出逻辑，以执行 简单的对象列表操作。 这一方法在处理某些对象时，需要引入不容忽视的逻辑。 此外，API 聚合 和定制资源 所提供的资源类型都是编译时不可预知的。这意味着，客户端必须针对无法 识别的类型提供通用的实现逻辑。

为了避免上述各种潜在的局限性，客户端可以请求服务器端返回对象的表格（Table） 表现形式，从而将打印输出的特定细节委托给服务器。 Kubernetes API 实现标准的 HTTP 内容类型（Content Type）协商：为 GET 调用 传入一个值为 application/json;as=Table;g=meta.k8s.io;v=v1beta1 的 Accept 头部即可请求服务器以 Table 的内容类型返回对象。

例如，以 Table 格式列举集群中所有 Pods：

GET /api/v1/pods
Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1
---
200 OK
Content-Type: application/json

{
    "kind": "Table",
    "apiVersion": "meta.k8s.io/v1beta1",
    ...
    "columnDefinitions": [
        ...
    ]
}

对于在服务器上不存在定制的 Table 定义的 API 资源类型而言，服务器会返回 一个默认的 Table 响应，其中包含资源的 name 和 creationTimestamp 字段。

GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
---
200 OK
Content-Type: application/json
...

{
    "kind": "Table",
    "apiVersion": "meta.k8s.io/v1beta1",
    ...
    "columnDefinitions": [
        {
            "name": "Name",
            "type": "string",
            ...
        },
        {
            "name": "Created At",
            "type": "date",
            ...
        }
    ]
}

kube-apiserver 从 1.10 版本开始提供 Table 响应。 因此，并非所有 API 资源类型都支持 Table 响应，尤其是使用客户端访问较老的集群时。 如果客户端需要能够处理所有资源类型，或者有可能需要与较老的集群交互， 则需要在其 Accept 头部设定多个内容类型值，以便可以回退到非表格形式的 JSON 表示。

Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1, application/json

资源的其他表示形式

默认情况下，Kubernetes 返回 JSON 序列化的的对象并设定内容类型为 application/json。这是 API 的默认序列化格式。 不过，客户端也可出于大规模环境中更佳性能的需求而请求对象的更为高效的 Protobuf 表现形式。 Kubernetes API 实现了标准的 HTTP 内容类型协商：为 GET 调用传递一个 Accept 头部来请求服务器以所指定的内容类型返回对象，同时在通过 PUT 或 POST 调用 向服务器发送 Protobuf 格式的对象时提供 Content-Type 头部。 服务器会能够支持所请求的格式时返回 Content-Type 头部，并在所提供的内容类型 不合法时返回 406 Not acceptable（无法接受） 错误。

请参阅 API 文档了解每个 API 所支持的内容类型。

例如：

1. 以 Protobuf 格式列举集群上的所有 Pods：

GET /api/v1/pods
Accept: application/vnd.kubernetes.protobuf
---
200 OK
Content-Type: application/vnd.kubernetes.protobuf

... binary encoded PodList object

2. 通过向服务器发送 Protobuf 编码的数据创建 Pod，但请求以 JSON 形式接收响应：

POST /api/v1/namespaces/test/pods
Content-Type: application/vnd.kubernetes.protobuf
Accept: application/json
... binary encoded Pod object
---
200 OK
Content-Type: application/json

{
  "kind": "Pod",
  "apiVersion": "v1",
  ...
}

并非所有 API 资源类型都支持 Protobuf，尤其是那些通过定制资源定义（CRD）或通过 API 扩展而加入的资源。如果客户端必须能够处理所有资源类型，则应在其 Accept 头部指定多种内容类型以便可以回退到 JSON 格式：

Accept: application/vnd.kubernetes.protobuf, application/json

Protobuf encoding

Kubernetes 使用封套形式来对 Protobuf 响应进行编码。 封套外层由 4 个字节的特殊数字开头，便于从磁盘文件或 etcd 中辩识 Protobuf 格式的（而不是 JSON）数据。 接下来存放的是 Protobuf 编码的封套消息，其中描述下层对象的编码和类型，最后 才是对象本身。

封套格式如下：

四个字节的特殊数字前缀：
  字节 0-3: "k8s\x00" [0x6b, 0x38, 0x73, 0x00]

使用下面 IDL 来编码的 Protobuf 消息：
  message Unknown {
    // typeMeta 应该包含 "kind" 和 "apiVersion" 的字符串值，就像
    // 对应的 JSON 对象中所设置的那样
    optional TypeMeta typeMeta = 1;

    // raw 中将保存用 protobuf 序列化的完整对象。
    // 参阅客户端库中为指定 kind 所作的 protobuf 定义
    optional bytes raw = 2;

    // contentEncoding 用于 raw 数据的编码格式。未设置此值意味着没有特殊编码。
    optional string contentEncoding = 3;

    // contentType 包含 raw 数据所采用的序列化方法。
    // 未设置此值意味着  application/vnd.kubernetes.protobuf，且通常被忽略
    optional string contentType = 4;
  }

  message TypeMeta {
    // apiVersion 是 type 对应的组名/版本
    optional string apiVersion = 1;
    // kind 是对象模式定义的名称。此对象应该存在一个 protobuf 定义。
    optional string kind = 2;
  }

收到 application/vnd.kubernetes.protobuf 格式响应的客户端在响应与预期的前缀 不匹配时应该拒绝响应，因为将来的版本可能需要以某种不兼容的方式更改序列化格式， 并且这种更改是通过变更前缀完成的。

资源删除

资源删除要经过两个阶段：1) 终止（finalization），和 2）去除。

{
  "kind": "ConfigMap",
  "apiVersion": "v1",
  "metadata": {
    "finalizers": {"url.io/neat-finalization", "other-url.io/my-finalizer"},
    "deletionTimestamp": nil,
  }
}

当客户端首先删除某资源时，其 .metadata.deletionTimestamp 会被设置为当前时间。 一旦 .metadata.deletionTimestamp 被设置，则对终结器（finalizers）执行动作 的外部控制器就可以在任何时候、以任何顺序执行其清理工作。 这里不强调顺序是因为很可能带来 .metadata.finalizers 被锁定的风险。 .metadata.finalizers 是一个共享的字段，任何具有相关权限的主体都可以对其 执行重排序的操作。如果终结器列表要按顺序处理，则很可能导致负责列表中第一个 终结器的组件要等待负责列表中排序靠后的终结器的组件的信号（可能是字段值变更、 外部系统或者其他形式），从而导致死锁行为。 在不对终结器顺序作强制要求的情况下，终结器可以自行排序，且不会因为其在列表 中的顺序而引入任何不稳定因素。

当最后一个终结器也被移除时，资源才真正从 etcd 中移除。

单个资源 API

API 动词 GET、CREATE、UPDATE、PATCH、DELETE 和 PROXY 仅支持单个资源。 这些支持单一资源的动词不支持以有序或无序列表甚或事务的形式同时提交给 多个资源。 包括 kubectl 在内的客户端将解析资源的列表，并执行单一资源的 API 请求。

API 动词 LIST 和 WATCH 支持获取多个资源，而 DELETECOLLECTION 支持删除多个 资源。

试运行

修改性质的动词（POST、PUT、PATCH 和 DELETE）可以支持 试运行（dry run） 模式的请求。试运行模式可帮助通过典型的请求阶段（准入控制链、合法性 检查、合并冲突）来评估请求，只是最终的对象不会写入存储。请求的响应主体与 非试运行模式下的响应尽可能接近。系统会保证试运行模式的请求不会被写入到存储 中，也不会产生其他副作用。

发起试运行请求

通过设置 dryRun 查询参数可以触发试运行模式。此参数是一个字符串，以枚举值 的形式工作且可接受的值只有：

• All：每个阶段被会正常运行，除了最后的存储阶段。准入控制器会被运行来检查请求 是否合法，变更性（Mutating）控制器会变更请求，PATCH 请求也会触发合并操作， 对象字段的默认值也会被设置，且基于模式定义的合法性检查也会被执行。 所生成的变更不会被写入到下层的持久性存储中，但本来会写入到数据库中的最终对象 会和正常的状态代码一起被返回给用户。如果请求会触发准入控制器而该准入控制器 带有一定的副作用，则请求会失败而不是冒险产生不希望的副作用。 所有的内置准入控制器插件都支持试运行模式。此外，准入控制 Webhook 也可在其 配置对象 中通过将 sideEffects 字段设置为 "None" 来声明自身不会产生副作用。 如果某 Webhook 确实会产生副作用，那么 sideEffects 字段应该设置为 "NoneOnDryRun"， 并且 Webhook 应该被更改以支持 AdmissionReview 中的 dryRun 字段，从而避免 在试运行时产生副作用。

• 空字符串（也即默认值）：保留默认的修改行为。

例如：

POST /api/v1/namespaces/test/pods?dryRun=All
Content-Type: application/json
Accept: application/json

响应会与非试运行模式请求的响应看起来相同，只是某些生成字段的值可能会不同。

试运行的授权

试运行和非试运行请求的鉴权是完全相同的。因此，要发起一个试运行请求，用户必须 被授权执行非试运行请求。

例如，要在 Deployment 对象上试运行 PATCH 操作，你必须具有对 Deployment 执行 PATCH 操作的访问权限，如下面的 RBAC 规则所示：

rules:
- apiGroups: ["extensions", "apps"]
  resources: ["deployments"]
  verbs: ["patch"]

参阅鉴权概述以了解鉴权细节。

生成的值

对象的某些值通常是在对象被写入数据库之前生成的。很重要的一点是不要依赖试运行 请求为这些字段所设置的值，因为试运行模式下所得到的这些值与真实请求所获得的 值很可能不同。这类字段有：

• name：如果设置了 generateName 字段，则 name 会获得一个唯一的随机名称
• creationTimestamp/deletionTimestamp：记录对象的创建/删除时间
• UID：唯一性标识对象，取值随机生成（非确定性）
• resourceVersion： 跟踪对象的持久化（存储）版本
• 变更性准入控制器所设置的字段
• 对于 Service 资源：kube-apiserver 为 v1.Service 对象分配的端口和 IP

服务器端应用

从 Kubernetes v1.18 开始，可以启用服务器端应用功能 特性，启用该特性后，控制面会跟踪所有新创建的对象的托管字段。服务器端应用提供了一种简洁的模式来管理字段冲突，提供服务器端的 Apply 和 Update 操作，并取代了 kubectl apply 的客户端功能。有关该特性的详细描述，请参见服务器端应用章节

资源版本

资源版本采用字符串来表达，用来标示对象的服务器端内部版本。 客户端可以使用资源版本来判定对象是否被更改，或者在读取、列举或监视资源时 用来表达数据一致性需求。 客户端必需将资源版本视为不透明的对象，将其原封不动地传递回服务器端。 例如，客户端一定不能假定资源版本是某种数值标识，也不可以对两个资源版本值 进行比较看其是否相同（也就是不可以比较两个版本值以判断其中一个比另一个 大或小）。

metadata 中的 resourceVersion

客户端可以在资源中看到资源版本信息，这里的资源包括从服务器返回的 Watch 事件 以及 list 操作响应：

v1.meta/ObjectMeta - 资源 的 metadata.resourceVersion 值标明该实例上次被更改时的资源版本。

v1.meta/ListMeta - 资源集合 （即 list 操作的响应）的 metadata.resourceVersion 所标明的是 list 响应被构造 时的资源版本。

resourceVersion 参数

GET、LIST 和 WATCH 操作都支持 resourceVersion 参数。

参数的具体含义取决于所执行的操作和所给的 resourceVersion 值：

对于 GET 和 LIST 而言，资源版本的语义为：

GET：

LIST：

v1.19 及以上版本的 API 服务器支持 resourceVersionMatch 参数，用以确定如何对 LIST 调用应用 resourceVersion 值。 强烈建议在为 LIST 调用设置了 resourceVersion 时也设置 resourceVersionMatch。 如果 resourceVersion 未设置，则 resourceVersionMatch 是不允许设置的。 为了向后兼容，客户端必须能够容忍服务器在某些场景下忽略 resourceVersionMatch 的行为：

• 当设置 resourceVersionMatch=NotOlderThan 且指定了 limit 时，客户端必须能够 处理 HTTP 410 "Gone" 响应。例如，客户端可以使用更新一点的 resourceVersion 来重试，或者回退到 resourceVersion="" （即允许返回任何版本）。

• 当设置了 resourceVersionMatch=Exact 且未指定 limit 时，客户端必须验证 响应数据中 ListMeta 的 resourceVersion 与所请求的 resourceVersion 匹配， 并处理二者可能不匹配的情况。例如，客户端可以重试设置了 limit 的请求。

除非你对一致性有着非常强烈的需求，使用 resourceVersionMatch=NotOlderThan 同时为 resourceVersion 设定一个已知值是优选的交互方式，因为与不设置 resourceVersion 和 resourceVersionMatch 相比，这种配置可以取得更好的 集群性能和可扩缩性。后者需要提供带票选能力的读操作。

脚注：

[1] 如果服务器无法正确处理 resourceVersionMatch 参数，其行为与未设置该参数相同。

GET 和 LIST 操作的语义含义如下：

• 最新版本： 返回资源版本为最新的数据。所返回的数据必须一致 （通过票选读操作从 etcd 中取出）。
• 任意版本： 返回任意资源版本的数据。优选最新可用的资源版本，不过不能保证 强一致性；返回的数据可能是任何资源版本的。请求返回的数据有可能是客户端以前 看到过的很老的资源版本。尤其在某些高可用配置环境中，网络分区或者高速缓存 未被更新等状态都可能导致这种状况。不能容忍这种不一致性的客户端不应采用此 语义。

• 不老于指定版本： 返回至少比所提供的 resourceVersion 还要新的数据。 优选最新的可用数据，不过最终提供的可能是不老于所给 resourceVersion 的任何版本。 对于发给能够正确处理 resourceVersionMatch 参数的服务器的 LIST 请求，此语义 保证 ListMeta 中的 resourceVersion 不老于请求的 resourceVersion，不过 不对列表条目之 ObjectMeta 的 resourceVersion 提供任何保证。 这是因为 ObjectMeta.resourceVersion 所跟踪的是列表条目对象上次更新的时间， 而不是对象被返回时是否是最新。

• 确定版本： 返回精确匹配所给资源版本的数据。如果所指定的 resourceVersion 的数据不可用，服务器会响应 HTTP 410 "Gone"。 对于发送给能够正确处理 resourceVersionMatch 参数的服务器的 LIST 请求而言， 此语义会保证 ListMeta 中的 resourceVersion 与所请求的 resourceVersion 匹配， 不过不对列表条目之 ObjectMeta 的 resourceVersion 提供任何保证。 这是因为 ObjectMeta.resourceVersion 所跟踪的是列表条目对象上次更新的时间， 而不是对象被返回时是否是最新。

• Continue 令牌、精确匹配： 返回原先带分页参数的 LIST 调用中指定的资源版本的数据。 在最初的带分页参数的 LIST 调用之后，所有分页式的 LIST 调用都使用所返回的 Continue 令牌来跟踪最初提供的资源版本，

对于 WATCH 操作而言，资源版本的语义如下：

WATCH：

WATCH 操作语义的含义如下：

• 读取状态并从最新版本开始： 从最新的资源版本开始 WATCH 操作。这里的 最新版本必须是一致的（即通过票选读操作从 etcd 中取出）。为了建立初始状态， WATCH 首先会处理一组合成的 "Added" 事件，这些事件涵盖在初始资源版本中存在 的所有资源实例。 所有后续的 WATCH 事件都是关于 WATCH 开始时所处资源版本之后发生的变更。

• 读取状态并从任意版本开始： 警告：通过这种方式初始化的 WATCH 操作可能会 返回任何状态的停滞数据。请在使用此语义之前执行复核，并在可能的情况下采用其他 语义。此语义会从任意资源版本开始执行 WATCH 操作，优选最新的可用的资源版本， 不过不是必须的；采用任何资源版本作为起始版本都是被允许的。 WATCH 操作有可能起始于客户端已经观测到的很老的版本。在高可用配置环境中，因为 网络分裂或者高速缓存未及时更新的原因都会造成此现象。 如果客户端不能容忍这种不一致性，就不要使用此语义来启动 WATCH 操作。 为了建立初始状态，WATCH 首先会处理一组合成的 "Added" 事件，这些事件涵盖在 初始资源版本中存在的所有资源实例。 所有后续的 WATCH 事件都是关于 WATCH 开始时所处资源版本之后发生的变更。

• 从指定版本开始： 从某确切资源版本开始执行 WATCH 操作。WATCH 事件都是 关于 WATCH 开始时所处资源版本之后发生的变更。与前面两种语义不同，WATCH 操作 开始的时候不会生成或处理为所提供资源版本合成的 "Added" 事件。 我们假定客户端既然能够提供确切资源版本，就应该已经拥有了起始资源版本对应的初始状态。

"410 Gone" 响应

服务器不需要提供所有老的资源版本，在客户端请求的是早于服务器端所保留版本的 resourceVersion 时，可以返回 HTTP 410 (Gone) 状态码。 客户端必须能够容忍 410 (Gone) 响应。 参阅高效检测变更以了解如何在监测资源时 处理 410 (Gone) 响应。

如果所请求的 resourceVersion 超出了可应用的 limit，那么取决于请求是否 是通过高速缓存来满足的，API 服务器可能会返回一个 410 Gone HTTP 响应。

不可用的资源版本

服务器不必未无法识别的资源版本提供服务。针对无法识别的资源版本的 LIST 和 GET 请求 可能会短暂等待，以期资源版本可用。如果所给的资源版本在一定的时间段内仍未变得 可用，服务器应该超时并返回 504 (Gateway Timeout)，且可在响应中添加 Retry-After 响应头部字段，标明客户端在再次尝试之前应该等待多少秒钟。 目前，kube-apiserver 也能使用 Too large resource version（资源版本过高） 消息来标识这类响应。针对某无法识别的资源版本的 WATCH 操作可能会无限期 （直到请求超时）地等待下去，直到资源版本可用。

2.2 - 服务器端应用（Server-Side Apply）

简介

服务器端应用协助用户、控制器通过声明式配置的方式管理他们的资源。 客户端可以发送完整描述的目标（A fully specified intent）， 声明式地创建和/或修改 对象。

一个完整描述的目标并不是一个完整的对象，仅包括能体现用户意图的字段和值。 该目标（intent）可以用来创建一个新对象， 也可以通过服务器来实现与现有对象的合并。

系统支持多个应用者（appliers）在同一个对象上开展协作。

“字段管理（field management）”机制追踪对象字段的变化。 当一个字段值改变时，其所有权从当前管理器（manager）转移到施加变更的管理器。 当尝试将新配置应用到一个对象时，如果字段有不同的值，且由其他管理器管理， 将会引发冲突。 冲突引发警告信号：此操作可能抹掉其他协作者的修改。 冲突可以被刻意忽略，这种情况下，值将会被改写，所有权也会发生转移。

当你从配置文件中删除一个字段，然后应用这个配置文件， 这将触发服务端应用检查此字段是否还被其他字段管理器拥有。 如果没有，那就从活动对象中删除该字段；如果有，那就重置为默认值。 该规则同样适用于 list 或 map 项目。

服务器端应用既是原有 kubectl apply 的替代品， 也是控制器发布自身变化的一个简化机制。

如果你启用了服务器端应用，控制平面就会跟踪被所有新创建对象管理的字段。

字段管理

相对于通过 kubectl 管理的注解 last-applied， 服务器端应用使用了一种更具声明式特点的方法： 它持续的跟踪用户的字段管理，而不仅仅是最后一次的执行状态。 这就意味着，作为服务器端应用的一个副作用， 关于用哪一个字段管理器负责管理对象中的哪个字段的这类信息，都要对外界开放了。

用户管理字段这件事，在服务器端应用的场景中，意味着用户依赖并期望字段的值不要改变。 最后一次对字段值做出断言的用户将被记录到当前字段管理器。 这可以通过发送 POST、 PUT、 或非应用（non-apply）方式的 PATCH 等命令来修改字段值的方式实现， 或通过把字段放在配置文件中，然后发送到服务器端应用的服务端点的方式实现。 当使用服务器端应用，尝试着去改变一个被其他人管理的字段， 会导致请求被拒绝（在没有设置强制执行时，参见冲突）。

如果两个或以上的应用者均把同一个字段设置为相同值，他们将共享此字段的所有权。 后续任何改变共享字段值的尝试，不管由那个应用者发起，都会导致冲突。 共享字段的所有者可以放弃字段的所有权，这只需从配置文件中删除该字段即可。

字段管理的信息存储在 managedFields 字段中，该字段是对象的 metadata 中的一部分。

服务器端应用创建对象的简单示例如下：

apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
  namespace: default
  labels:
    test-label: test
  managedFields:
  - manager: kubectl
    operation: Apply
    apiVersion: v1
    time: "2010-10-10T0:00:00Z"
    fieldsType: FieldsV1
    fieldsV1:
      f:metadata:
        f:labels:
          f:test-label: {}
      f:data:
        f:key: {}
data:
  key: some value

上述对象在 metadata.managedFields 中包含了唯一的管理器。 管理器由管理实体自身的基本信息组成，比如操作类型、API 版本、以及它管理的字段。

说明： 该字段由 API 服务器管理，用户不应该改动它。

不过，执行 Update 操作修改 metadata.managedFields 也是可实现的。 强烈不鼓励这么做，但当发生如下情况时， 比如 managedFields 进入不一致的状态（显然不应该发生这种情况）， 这么做也是一个合理的尝试。

managedFields 的格式在 API 文档中描述。

冲突

冲突是一种特定的错误状态， 发生在执行 Apply 改变一个字段，而恰巧该字段被其他用户声明过主权时。 这可以防止一个应用者不小心覆盖掉其他用户设置的值。 冲突发生时，应用者有三种办法来解决它：

• 覆盖前值，成为唯一的管理器： 如果打算覆盖该值（或应用者是一个自动化部件，比如控制器）， 应用者应该设置查询参数 force 为 true，然后再发送一次请求。 这将强制操作成功，改变字段的值，从所有其他管理器的 managedFields 条目中删除指定字段。

• 不覆盖前值，放弃管理权： 如果应用者不再关注该字段的值， 可以从配置文件中删掉它，再重新发送请求。 这就保持了原值不变，并从 managedFields 的应用者条目中删除该字段。

• 不覆盖前值，成为共享的管理器： 如果应用者仍然关注字段值，并不想覆盖它， 他们可以在配置文件中把字段的值改为和服务器对象一样，再重新发送请求。 这样在不改变字段值的前提下， 就实现了字段管理被应用者和所有声明了管理权的其他的字段管理器共享。

管理器

管理器识别出正在修改对象的工作流程（在冲突时尤其有用）, 管理器可以通过修改请求的参数 fieldManager 指定。 虽然 kubectl 默认发往 kubectl 服务端点，但它则请求到应用的服务端点（apply endpoint）。 对于其他的更新，它默认的是从用户代理计算得来。

应用和更新

此特性涉及两类操作，分别是 Apply （内容类型为 application/apply-patch+yaml 的 PATCH 请求） 和 Update （所有修改对象的其他操作）。 这两类操作都会更新字段 managedFields，但行为表现有一点不同。

说明：

不管你提交的是 JSON 数据还是 YAML 数据， 都要使用 application/apply-patch+yaml 作为 Content-Type 的值。

所有的 JSON 文档 都是合法的 YAML。

例如，在冲突发生的时候，只有 apply 操作失败，而 update 则不会。 此外，apply 操作必须通过提供一个 fieldManager 查询参数来标识自身， 而此查询参数对于 update 操作则是可选的。 最后，当使用 apply 命令时，你不能在应用中的对象中持有 managedFields。

一个包含多个管理器的对象，示例如下：

apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
  namespace: default
  labels:
    test-label: test
  managedFields:
  - manager: kubectl
    operation: Apply
    apiVersion: v1
    fields:
      f:metadata:
        f:labels:
          f:test-label: {}
  - manager: kube-controller-manager
    operation: Update
    apiVersion: v1
    time: '2019-03-30T16:00:00.000Z'
    fields:
      f:data:
        f:key: {}
data:
  key: new value

在这个例子中， 第二个操作被管理器 kube-controller-manager 以 Update 的方式运行。 此 update 更改 data 字段的值， 并使得字段管理器被改为 kube-controller-manager。

如果把 update 操作改为 Apply，那就会因为所有权冲突的原因，导致操作失败。

合并策略

由服务器端应用实现的合并策略，提供了一个总体更稳定的对象生命周期。 服务器端应用试图依据负责管理它们的主体来合并字段，而不是根据值来否决。 这么做是为了多个主体可以更新同一个对象，且不会引起意外的相互干扰。

当用户发送一个“完整描述的目标”对象到服务器端应用的服务端点， 服务器会将它和活动对象做一次合并，如果两者中有重复定义的值，那就以配置文件的为准。 如果配置文件中的项目集合不是此用户上一次操作项目的超集， 所有缺少的、没有其他应用者管理的项目会被删除。 关于合并时用来做决策的对象规格的更多信息，参见 sigs.k8s.io/structured-merge-diff.

Kubernetes 1.16 和 1.17 中添加了一些标记， 允许 API 开发人员描述由 list、map、和 structs 支持的合并策略。 这些标记可应用到相应类型的对象，在 Go 文件或在 CRD 的 OpenAPI 的模式中定义：

若未指定 listType，API 服务器将 patchMergeStrategy=merge 标记解释为 listType=map 并且视对应的 patchMergeKey 标记为 listMapKey 取值。

atomic 列表类型是递归的。

这些标记都是用源代码注释的方式给出的，不必作为字段标签（tag）再重复。

拓扑变化时的兼容性

在极少的情况下，CRD 或者内置类型的作者可能希望更改其资源中的某个字段的 拓扑配置，同时又不提升版本号。 通过升级集群或者更新 CRD 来更改类型的拓扑信息与更新现有对象的结果不同。 变更的类型有两种：一种是将字段从 map/set/granular 更改为 atomic， 另一种是做逆向改变。

当 listType、mapType 或 structType 从 map/set/granular 改为 atomic 时，现有对象的整个列表、映射或结构的属主都会变为这些类型的 元素之一的属主。这意味着，对这些对象的进一步变更会引发冲突。

当一个列表、映射或结构从 atomic 改为 map/set/granular 之一 时，API 服务器无法推导这些字段的新的属主。因此，当对象的这些字段 再次被更新时不会引发冲突。出于这一原因，不建议将某类型从 atomic 改为 map/set/granular。

以下面的自定义资源为例：

apiVersion: example.com/v1
kind: Foo
metadata:
  name: foo-sample
  managedFields:
  - manager: manager-one
    operation: Apply
    apiVersion: example.com/v1
    fields:
      f:spec:
        f:data: {}
spec:
  data:
    key1: val1
    key2: val2

在 spec.data 从 atomic 改为 granular 之前，manager-one 是 spec.data 字段及其所包含字段（key1 和 key2）的属主。 当对应的 CRD 被更改，使得 spec.data 变为 granular 拓扑时， manager-one 继续拥有顶层字段 spec.data（这意味着其他管理者想 删除名为 data 的映射而不引起冲突是不可能的），但不再拥有 key1 和 key2。因此，其他管理者可以在不引起冲突的情况下更改 或删除这些字段。

自定义资源

默认情况下，服务器端应用把自定义资源看做非结构化数据。 所有的键值（keys）就像 struct 的字段一样被处理， 所有的 list 被认为是原子性的。

如果自定义资源定义（Custom Resource Definition，CRD）定义了一个 模式， 它包含类似以前“合并策略”章节中定义过的注解， 这些注解将在合并此类型的对象时使用。

在控制器中使用服务器端应用

控制器的开发人员可以把服务器端应用作为简化控制器的更新逻辑的方式。 读-改-写 和/或 patch 的主要区别如下所示：

• 应用的对象必须包含控制器关注的所有字段。
• 对于在控制器没有执行过应用操作之前就已经存在的字段，不能删除。 （控制器在这种用例环境下，依然可以发送一个 PATCH/UPDATE）
• 对象不必事先读取，resourceVersion 不必指定。

强烈推荐：设置控制器在冲突时强制执行，这是因为冲突发生时，它们没有其他解决方案或措施。

转移所有权

除了通过冲突解决方案提供的并发控制， 服务器端应用提供了一些协作方式来将字段所有权从用户转移到控制器。

最好通过例子来说明这一点。 让我们来看看，在使用 Horizo​​ntalPodAutoscaler 资源和与之配套的控制器， 且开启了 Deployment 的自动水平扩展功能之后， 怎么安全的将 replicas 字段的所有权从用户转移到控制器。

假设用户定义了 Deployment，且 replicas 字段已经设置为期望的值：

application/ssa/nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2

并且，用户使用服务器端应用，像这样创建 Deployment：

kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment.yaml --server-side

然后，为 Deployment 启用 HPA，例如：

kubectl autoscale deployment nginx-deployment --cpu-percent=50 --min=1 --max=10

现在，用户希望从他们的配置中删除 replicas，所以他们总是和 HPA 控制器冲突。 然而，这里存在一个竟态： 在 HPA 需要调整 replicas 之前会有一个时间窗口， 如果在 HPA 写入字段成为所有者之前，用户删除了replicas， 那 API 服务器就会把 replicas 的值设为1， 也就是默认值。 这不是用户希望发生的事情，即使是暂时的。

这里有两个解决方案：

• （基本操作）把 replicas 留在配置文件中；当 HPA 最终写入那个字段， 系统基于此事件告诉用户：冲突发生了。在这个时间点，可以安全的删除配置文件。
• （高级操作）然而，如果用户不想等待，比如他们想为合作伙伴保持集群清晰， 那他们就可以执行以下步骤，安全的从配置文件中删除 replicas。

首先，用户新定义一个只包含 replicas 字段的配置文件：

application/ssa/nginx-deployment-replicas-only.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3

用户使用名为 handover-to-hpa 的字段管理器，应用此配置文件。

kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment-replicas-only.yaml \
  --server-side --field-manager=handover-to-hpa \
  --validate=false

如果应用操作和 HPA 控制器产生冲突，那什么都不做。 冲突表明控制器在更早的流程中已经对字段声明过所有权。

在此时间点，用户可以从配置文件中删除 replicas 。

application/ssa/nginx-deployment-no-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2

注意，只要 HPA 控制器为 replicas 设置了一个新值， 该临时字段管理器将不再拥有任何字段，会被自动删除。 这里不需要执行清理工作。

在用户之间转移所有权

通过在配置文件中把一个字段设置为相同的值，用户可以在他们之间转移字段的所有权， 从而共享了字段的所有权。 当用户共享了字段的所有权，任何一个用户可以从他的配置文件中删除该字段， 并应用该变更，从而放弃所有权，并实现了所有权向其他用户的转移。

与客户端应用的对比

由服务器端应用实现的冲突检测和解决方案的一个结果就是， 应用者总是可以在本地状态中得到最新的字段值。 如果得不到最新值，下次执行应用操作时就会发生冲突。 解决冲突三个选项的任意一个都会保证：此应用过的配置文件是服务器上对象字段的最新子集。

这和客户端应用（Client Side Apply） 不同，如果有其他用户覆盖了此值， 过期的值被留在了应用者本地的配置文件中。 除非用户更新了特定字段，此字段才会准确， 应用者没有途径去了解下一次应用操作是否会覆盖其他用户的修改。

另一个区别是使用客户端应用的应用者不能改变他们正在使用的 API 版本，但服务器端应用支持这个场景。

从客户端应用升级到服务器端应用

客户端应用方式时，用户使用 kubectl apply 管理资源， 可以通过使用下面标记切换为使用服务器端应用。

kubectl apply --server-side [--dry-run=server]

默认情况下，对象的字段管理从客户端应用方式迁移到 kubectl 触发的服务器端应用时，不会发生冲突。

注意：

保持注解 last-applied-configuration 是最新的。 从注解能推断出字段是由客户端应用管理的。 任何没有被客户端应用管理的字段将引发冲突。

举例说明，比如你在客户端应用之后， 使用 kubectl scale 去更新 replicas 字段， 可是该字段并没有被客户端应用所拥有， 在执行 kubectl apply --server-side 时就会产生冲突。

此操作以 kubectl 作为字段管理器来应用到服务器端应用。 作为例外，可以指定一个不同的、非默认字段管理器停止的这种行为，如下面的例子所示。 对于 kubectl 触发的服务器端应用，默认的字段管理器是 kubectl。

kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

从服务器端应用降级到客户端应用

如果你用 kubectl apply --server-side 管理一个资源， 可以直接用 kubectl apply 命令将其降级为客户端应用。

降级之所以可行，这是因为 kubectl server-side apply 会保存最新的 last-applied-configuration 注解。

此操作以 kubectl 作为字段管理器应用到服务器端应用。 作为例外，可以指定一个不同的、非默认字段管理器停止这种行为，如下面的例子所示。 对于 kubectl 触发的服务器端应用，默认的字段管理器是 kubectl。

kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

API 端点

启用了服务器端应用特性之后， PATCH 服务端点接受额外的内容类型 application/apply-patch+yaml。 服务器端应用的用户就可以把 YAMl 格式的 部分定义对象（partially specified objects）发送到此端点。 当一个配置文件被应用时，它应该包含所有体现你意图的字段。

清除 ManagedFields

可以从对象中剥离所有 managedField， 实现方法是通过使用 MergePatch、 StrategicMergePatch、 JSONPatch、 Update、以及所有的非应用方式的操作来覆盖它。 这可以通过用空条目覆盖 managedFields 字段的方式实现。

PATCH /api/v1/namespaces/default/configmaps/example-cm
Content-Type: application/merge-patch+json
Accept: application/json
Data: {"metadata":{"managedFields": [{}]}}

PATCH /api/v1/namespaces/default/configmaps/example-cm
Content-Type: application/json-patch+json
Accept: application/json
Data: [{"op": "replace", "path": "/metadata/managedFields", "value": [{}]}]

这一操作将用只包含一个空条目的列表覆写 managedFields， 来实现从对象中整个的去除 managedFields。 注意，只把 managedFields 设置为空列表并不会重置字段。 这么做是有目的的，所以 managedFields 将永远不会被与该字段无关的客户删除。

在重置操作结合 managedFields 以外其他字段更改的场景中， 将导致 managedFields 首先被重置，其他改变被押后处理。 其结果是，应用者取得了同一个请求中所有字段的所有权。

注意： 对于不接受资源对象类型的子资源（sub-resources）， 服务器端应用不能正确地跟踪其所有权。 如果你对这样的子资源使用服务器端应用，变更的字段将不会被跟踪。

禁用此功能

服务器端应用是一个 Beta 版特性，默认启用。 要关闭此特性门控， 你需要在启动 kube-apiserver 时包含参数 --feature-gates ServerSideApply=false。 如果你有多个 kube-apiserver 副本，它们的标志设置应该都相同。

2.3 - 客户端库

本页面包含基于各种编程语言使用 Kubernetes API 的客户端库概述。

在使用 Kubernetes REST API 编写应用程序时， 您并不需要自己实现 API 调用和 “请求/响应” 类型。 您可以根据自己的编程语言需要选择使用合适的客户端库。

客户端库通常为您处理诸如身份验证之类的常见任务。 如果 API 客户端在 Kubernetes 集群中运行，大多数客户端库可以发现并使用 Kubernetes 服务帐户进行身份验证， 或者能够理解 kubeconfig 文件 格式来读取凭据和 API 服务器地址。

官方支持的 Kubernetes 客户端库

以下客户端库由 Kubernetes SIG API Machinery 正式维护。

社区维护的客户端库

注意： 本部分链接到提供 Kubernetes 所需功能的第三方项目。Kubernetes 项目作者不负责这些项目。此页面遵循CNCF 网站指南，按字母顺序列出项目。要将项目添加到此列表中，请在提交更改之前阅读内容指南。

以下 Kubernetes API 客户端库是由社区，而非 Kubernetes 团队支持、维护的。

2.4 - Kubernetes 弃用策略

本文档详细解释系统中各个层面的弃用策略（Deprecation Policy）。

Kubernetes 是一个组件众多、贡献者人数众多的大系统。 就像很多类似的软件，所提供的功能特性集合会随着时间推移而自然发生变化， 而且有时候某个功能特性可能需要被去除。被去除的可能是一个 API、一个参数标志或者 甚至某整个功能特性。为了避免影响到现有用户，Kubernetes 对于其中渐次移除 的各个方面规定了一种弃用策略并遵从此策略。

弃用 API 的一部分

由于 Kubernetes 是一个 API 驱动的系统，API 会随着时间推移而演化，以反映 人们对问题空间的认识的变化。Kubernetes API 实际上是一个 API 集合，其中每个 成员称作“API 组（API Group）”，并且每个 API 组都是独立管理版本的。 API 版本会有 三类，每类有不同的废弃策略：

给定的 Kubernetes 发布版本中可以支持任意数量的 API 组，且每组可以包含 任意个数的版本。

下面的规则负责指导 API 元素的弃用，具体元素包括：

• REST 资源（也即 API 对象）
• REST 资源的字段
• REST 资源的注解，包含“beta”类注解但不包含“alpha”类注解
• 枚举值或者常数值
• 组件配置结构

以下是跨正式发布版本时要实施的规则，不适用于对 master 或发布分支上 不同提交之间的变化。

规则 #1：只能在增加 API 组版本号时删除 API 元素。

一旦在某个特定 API 组版本中添加了 API 元素，则该元素不可从该版本中删除， 且其行为也不能大幅度地变化，无论属于哪一类（GA、Alpha 或 Beta）。

说明： 由于历史原因，Kubernetes 中存在两个“单体式（Monolithic）”API 组 - “core”（无组名）和“extensions”。这两个遗留 API 组中的资源会被逐渐迁移到 更为特定领域的 API 组中。

规则 #2：在给定的发布版本中，API 对象必须能够在不同的 API 版本之间来回 转换且不造成信息丢失，除非整个 REST 资源在某些版本中完全不存在。

例如，一个对象可被用 v1 来写入之后用 v2 来读出并转换为 v1，所得到的 v1 必须 与原来的 v1 对象完全相同。v2 中的表现形式可能与 v1 不同，但系统知道如何 在两个版本之间执行双向转换。 此外，v2 中添加的所有新字段都必须能够转换为 v1 再转换回来。这意味着 v1 必须 添加一个新的等效字段或者将其表现为一个注解。

规则 #3：给定类别的 API 版本在新的、稳定性未降低的 API 版本发布之前不可被废弃。

一个正式发布的（GA）API 版本可替换现有的正式 API 版本或 alpha、beta API 版本。 Beta API 版本 不可以 替代正式的 API 版本。

规则 #4a：除了每类 API 版本中的最新版本，旧的 API 版本在其被宣布被废弃之后 至少以下时长内仍需被支持：

• GA：12 个月或者 3 个发布版本（取其较长者）
• Beta: 9 个月或者 3 个发布版本（取其较长者）
• Alpha: 0 个发布版本

这里也包含了关于最大支持 2 个发布版本的版本偏差 的约定。

说明： 在 #52185 被解决之前， 已经被保存到持久性存储中的 API 版本都不可以被去除。 你可以禁止这些版本所对应的 REST 末端（在符合本文中弃用时间线的前提下）， 但是 API 服务器必须仍能解析和转换存储中以前写入的数据。

规则 #4b：标记为“preferred（优选的）” API 版本和给定 API 组的 “storage version（存储版本）”在既支持老版本也支持新版本的 Kubernetes 发布 版本出来以前不可以提升其版本号。

用户必须能够升级到 Kubernetes 新的发行版本，之后再回滚到前一个发行版本，且 整个过程中无需针对新的 API 版本做任何转换，也不允许出现功能损坏的情况， 除非用户显式地使用了仅在较新版本中才存在的功能特性。 就对象的存储表示而言，这一点尤其是不言自明的。

以上所有规则最好通过例子来说明。假定现有 Kubernetes 发行版本为 X，其中引入了 新的 API 组。大约每隔 3 个月会有一个新的 Kubernetes 版本被发布（每年 4 个版本）。 下面的表格描述了在一系列后续的发布版本中哪些 API 版本是受支持的。

REST 资源（也即 API 对象）

考虑一个假想的名为 Widget 的 REST 资源，在上述时间线中位于 API v1， 而现在打算将其弃用。 我们会在文档和 声明 中与 X+1 版本的发布同步记述此弃用决定。 Wdiget 资源仍会在 API 版本 v1（已弃用）中存在，但不会出现在 v2alpha1 中。 Widget 资源会 X+8 发布版本之前（含 X+8）一直存在并可用。 只有在发布版本 X+9 中，API v1 寿终正寝时，Widget 才彻底消失，相应的资源行为也被移除。

从 Kubernetes v1.19 开始，当 API 请求被发送到一个已弃用的 REST API 末端时：

1. API 响应中会包含一个 Warning 头部字段（如 RFC7234 5.5 节所定义）；

2. 该请求会导致对应的 审计事件 中会增加一个注解 "k8s.io/deprecated":"true"。

3. kube-apiserver 进程的 apiserver_requested_deprecated_apis 度量值会被 设置为 1。 该度量值还附带 group、version、resource 和 subresource 标签 （可供添加到度量值 apiserver_request_total 上）， 和一个 removed_release 标签，标明该 API 将消失的 Kubernetes 发布版本。 下面的 Prometheus 查询会返回对 v1.22 中将移除的、已弃用的 API 的请求的信息：

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

REST 资源的字段

就像整个 REST 资源一样，在 API v1 中曾经存在的各个字段在 API v1 被移除 之前必须一直存在且起作用。 与整个资源上的规定不同，v2 API 可以选择为字段提供不同的表示方式， 只要对应的资源对象可在不同版本之间来回转换即可。 例如，v1 版本中一个名为 "magnitude" 的已弃用字段可能在 API v2 中被命名 为 "deprecatedMagnitude"。当 v1 最终被移除时，废弃的字段也可以从 v2 中移除。

枚举值或常数值

就像前文讲述的 REST 资源及其中的单个字段一样，API v1 中所支持的常数值 必须在 API v1 被移除之前一直存在且起作用。

组件配置结构

组件的配置也是有版本的，并且按 REST 资源的方式来管理。

将来的工作

随着时间推移，Kubernetes 会引入粒度更细的 API 版本。 到那时，这里的规则会根据需要进行调整。

弃用一个标志或 CLI 命令

Kubernetes 系统中包含若干不同的、相互协作的程序。 有时，Kubernetes 可能会删除这些程序的某些标志或 CLI 命令（统称“命令行元素”）。 这些程序可以天然地划分到两个大组中：面向用户的和面向管理员的程序。 二者之间的弃用策略略有不同。 除非某个标志显示地通过前缀或文档来标明其为“alpha”或“beta”， 该标志要被视作正式发布的（GA）。

命令行元素相当于系统的 API 的一部分，不过因为它们并没有采用 REST API 一样的方式来管理版本，其弃用规则规定如下：

规则 #5a：面向用户的命令行元素（例如，kubectl）必须在其宣布被弃用其 在以下时长内仍能使用：

• GA：12 个月或者 2 个发布版本（取其较长者）
• Beta：3 个月或者 1 个发布版本（取其较长者）
• Alpha：0 发布版本

规则 #5b：面向管理员的命令行元素（例如，kubelet）必须在其被宣布弃用 之后以下时长内保持可用：

• GA：6 个月或 1 个发行版本（取其较长者）
• Beta: 3 个月或 1 个发行版本（取其较长者）
• Alpha: 0 个发布版本

规则 #6：被弃用的 CLI 元素在被用到时必须能够产生警告，而警告的 产生是可以被禁止的。

弃用某功能特性或行为

在一些较偶然的情形下，某 Kubernetes 发行版本需要弃用系统的某项功能 特性或者行为，而对应的功能特性或行为并不受 API 或 CLI 控制。在这种情况下， 其弃用规则如下：

规则 #7：被弃用的行为必须在被宣布弃用之后至少 1 年时间内必须保持能用。

这并不意味着对系统的所有更改都受此策略约束。 此规则仅适用于重大的、用户可见的行为；这些行为会影响到在 Kubernetes 中运行的应用的正确性，或者影响到 Kubernetes 集群的管理。 此规则也适用于那些被整个移除的功能特性或行为。

上述规则的一个例外是 特性门控（Feature Gates）。特性门控是一些键值偶对， 允许用户启用或禁用一些试验性的功能特性。

特性门控意在覆盖功能特性的整个开发周期，它们无意成为长期的 API。 因此，它们会在某功能特性正式发布或被抛弃之后被弃用和删除。

随着一个功能特性经过不同的成熟阶段，相关的特性门控也会演化。 与功能特性生命周期对应的特性门控状态为：

• Alpha：特性门控默认被禁用，只能由用户显式启用。
• Beta：特性门控默认被弃用，可被用户显式禁用。
• GA: 特性门控被弃用（参见弃用），并且不再起作用。
• GA，弃用窗口期结束：特性门控被删除，不再接受调用。

弃用

功能特性在正式发布之前的生命周期内任何时间点都可被移除。 当未正式发布的功能特性被移除时，它们对应的特性门控也被弃用。

当尝试禁用一个不再起作用的特性门控时，该调用会失败，这样可以避免 毫无迹象地执行一些不受支持的场景。

在某些场合，移除一个即将正式发布的功能特性需要很长时间。特性门控 可以保持其功能，直到对应的功能特性被彻底去除，直到那时特性门控 自身才可被弃用。

由于移除一个已经正式发布的功能特性对应的特性门控也需要一定时间，对特性 门控的调用可能一直被允许，前提是特性门控对功能本身无影响且特性门控不会 引发任何错误。

意在允许用户禁用的功能特性应该包含一个在相关联的特性门控中禁用该功能的机制。

特性门控的版本管理与之前讨论的组件版本管理不同，因此其对应的弃用策略如下：

规则 #8：特性门控所对应的功能特性经历下面所列的成熟性阶段转换时，特性门控 必须被弃用。特性门控弃用时必须在以下时长内保持其功能可用：

• Beta 特性转为 GA：6 个月或者 2 个发布版本（取其较长者）
• Beta 特性转为丢弃：3 个月或者 1 个发布版本（取其较长者）
• Alpha 特性转为丢弃：0 个发布版本

规则 #9：已弃用的特色门控再被使用时必须给出警告回应。当特性门控被 弃用时，必须在发布说明和对应的 CLI 帮助信息中通过文档宣布。 警告信息和文档都要标明是否某特性门控不再起作用。

弃用度量值

Kubernetes 控制平面的每个组件都公开度量值（通常是 /metrics 端点），它们通常由集群管理员使用。 并不是所有的度量值都是同样重要的：一些度量值通常用作 SLIs 或被使用来确定 SLOs，这些往往比较重要。 其他度量值在本质上带有实验性，或者主要用于 Kubernetes 开发过程。

因此，度量值分为两个稳定性类别（ALPHA 和 STABLE）; 此分类会影响在 Kubernetes 发布版本中移除某度量值。 所对应的分类取决于对该度量值重要性的预期。 弃用和移除度量值的规则如下：

规则 #9a: 对于相应的稳定性类别，度量值起作用的周期必须不小于：

• STABLE: 4 个发布版本或者 12 个月 (取其较长者)
• ALPHA: 0 个发布版本

规则 #9b: 在度量值被宣布启用之后，它起作用的周期必须不小于：

• STABLE: 3 个发布版本或者 9 个月 (取其较长者)
• ALPHA: 0 个发布版本

已弃用的度量值将在其描述文本前加上一个已弃用通知字符串 '(Deprecated from x.y)'， 并将在度量值被记录期间发出警告日志。就像稳定的、未被弃用的度量指标一样， 被弃用的度量值将自动注册到 metrics 端点，因此被弃用的度量值也是可见的。

在随后的版本中（当度量值 deprecatedVersion 等于_当前 Kubernetes 版本 - 3_）， 被弃用的度量值将变成 _隐藏（Hidden）_ metric 度量值。 与被弃用的度量值不同，隐藏的度量值将不再被自动注册到 metrics 端点（因此被隐藏）。 但是，它们可以通过可执行文件的命令行标志显式启用 （--show-hidden-metrics-for-version=）。 如果集群管理员不能对早期的弃用警告作出反应，这一设计就为他们提供了抓紧迁移弃用度量值的途径。 隐藏的度量值应该在再过一个发行版本后被删除。

例外

没有策略可以覆盖所有情况。此策略文档是一个随时被更新的文档，会随着时间 推移演化。在实践中，会有一些情况无法很好地匹配到这里的弃用策略，或者 这里的策略变成了很严重的羁绊。这类情形要与 SIG 和项目牵头人讨论， 寻求对应场景的最佳解决方案。请一直铭记，Kubernetes 承诺要成为一个 稳定的系统，至少会尽力做到不会影响到其用户。此弃用策略的任何例外情况 都会在所有相关的发布说明中公布。

2.5 - Kubernetes API 健康端点

Kubernetes API 服务器 提供 API 端点以指示 API 服务器的当前状态。 本文描述了这些 API 端点，并说明如何使用。

API 健康端点

Kubernetes API 服务器提供 3 个 API 端点（healthz、livez 和 readyz）来表明 API 服务器的当前状态。 healthz 端点已被弃用（自 Kubernetes v1.16 起），你应该使用更为明确的 livez 和 readyz 端点。 livez 端点可与 --livez-grace-period 标志一起使用，来指定启动持续时间。 为了正常关机，你可以使用 /readyz 端点并指定 --shutdown-delay-duration 标志。 检查 API 服务器的 healthz/livez/readyz 端点的机器应依赖于 HTTP 状态代码。 状态码 200 表示 API 服务器是 healthy、live 还是 ready，具体取决于所调用的端点。 以下更详细的选项供操作人员使用，用来调试其集群或专门调试 API 服务器的状态。

以下示例将显示如何与运行状况 API 端点进行交互。

对于所有端点，都可以使用 verbose 参数来打印检查项以及检查状态。 这对于操作人员调试 API 服务器的当前状态很有用，这些不打算给机器使用：

curl -k https://localhost:6443/livez?verbose

或从具有身份验证的远程主机：

kubectl get --raw='/readyz?verbose'

输出将如下所示：

[+]ping ok
[+]log ok
[+]etcd ok
[+]poststarthook/start-kube-apiserver-admission-initializer ok
[+]poststarthook/generic-apiserver-start-informers ok
[+]poststarthook/start-apiextensions-informers ok
[+]poststarthook/start-apiextensions-controllers ok
[+]poststarthook/crd-informer-synced ok
[+]poststarthook/bootstrap-controller ok
[+]poststarthook/rbac/bootstrap-roles ok
[+]poststarthook/scheduling/bootstrap-system-priority-classes ok
[+]poststarthook/start-cluster-authentication-info-controller ok
[+]poststarthook/start-kube-aggregator-informers ok
[+]poststarthook/apiservice-registration-controller ok
[+]poststarthook/apiservice-status-available-controller ok
[+]poststarthook/kube-apiserver-autoregistration ok
[+]autoregister-completion ok
[+]poststarthook/apiservice-openapi-controller ok
healthz check passed

Kubernetes API 服务器也支持排除特定的检查项。 查询参数也可以像以下示例一样进行组合：

curl -k 'https://localhost:6443/readyz?verbose&exclude=etcd'

输出显示排除了 etcd 检查：

[+]ping ok
[+]log ok
[+]etcd excluded: ok
[+]poststarthook/start-kube-apiserver-admission-initializer ok
[+]poststarthook/generic-apiserver-start-informers ok
[+]poststarthook/start-apiextensions-informers ok
[+]poststarthook/start-apiextensions-controllers ok
[+]poststarthook/crd-informer-synced ok
[+]poststarthook/bootstrap-controller ok
[+]poststarthook/rbac/bootstrap-roles ok
[+]poststarthook/scheduling/bootstrap-system-priority-classes ok
[+]poststarthook/start-cluster-authentication-info-controller ok
[+]poststarthook/start-kube-aggregator-informers ok
[+]poststarthook/apiservice-registration-controller ok
[+]poststarthook/apiservice-status-available-controller ok
[+]poststarthook/kube-apiserver-autoregistration ok
[+]autoregister-completion ok
[+]poststarthook/apiservice-openapi-controller ok
[+]shutdown ok
healthz check passed

独立健康检查

每个单独的健康检查都会公开一个 HTTP 端点，并且可以单独检查。 单个运行状况检查的模式为 /livez/<healthcheck-name>，其中 livez 和 readyz 表明你要检查的是 API 服务器是否存活或就绪。 <healthcheck-name> 的路径可以通过上面的 verbose 参数发现 ，并采用 [+] 和 ok 之间的路径。 这些单独的健康检查不应由机器使用，但对于操作人员调试系统而言，是有帮助的：

curl -k https://localhost:6443/livez/etcd

3 - 常见的标签、注解和污点

Kubernetes 预留命名空间 kubernetes.io 用于所有的标签和注解。

本文档有两个作用，一是作为可用值的参考，二是作为赋值的协调点。

kubernetes.io/arch

示例：kubernetes.io/arch=amd64

用于：Node

Kubelet 用 Go 定义的 runtime.GOARCH 生成该标签的键值。在混合使用 arm 和 x86 节点的场景中，此键值可以带来极大便利。

kubernetes.io/os

示例：kubernetes.io/os=linux

用于：Node

Kubelet 用 Go 定义的 runtime.GOOS 生成该标签的键值。在混合使用异构操作系统场景下（例如：混合使用 Linux 和 Windows 节点），此键值可以带来极大便利。

kubernetes.io/metadata.name

示例：kubernetes.io/metadata.name=mynamespace

用于：Namespaces

当 NamespaceDefaultLabelName 特性门控 被启用时，Kubernetes API 服务器会在所有命名空间上设置此标签。标签值被设置为命名空间的名称。

如果你想使用标签 选择器 来指向特定的命名空间，这很有用。

beta.kubernetes.io/arch (deprecated)

此标签已被弃用，取而代之的是 kubernetes.io/arch.

beta.kubernetes.io/os (deprecated)

此标签已被弃用，取而代之的是 kubernetes.io/os.

kubernetes.io/hostname

示例：kubernetes.io/hostname=ip-172-20-114-199.ec2.internal

用于：Node

Kubelet 用主机名生成此标签。需要注意的是主机名可修改，这是把“实际的”主机名通过参数 --hostname-override 传给 kubelet 实现的。

此标签也可用做拓扑层次的一个部分。更多信息参见topology.kubernetes.io/zone。

controller.kubernetes.io/pod-deletion-cost

示例：controller.kubernetes.io/pod-deletion-cost=10

用于：Pod

该注解用于设置 Pod 删除开销， 允许用户影响 ReplicaSet 的缩减顺序。该注解解析为 int32 类型。

beta.kubernetes.io/instance-type (deprecated)

说明：

从 v1.17 起，此标签被弃用，取而代之的是 node.kubernetes.io/instance-type.

node.kubernetes.io/instance-type

示例：node.kubernetes.io/instance-type=m3.medium

用于：Node

Kubelet 用 cloudprovider 定义的实例类型生成此标签。 所以只有用到 cloudprovider 的场合，才会设置此标签。 此标签非常有用，特别是在你希望把特定工作负载打到特定实例类型的时候，但更常见的调度方法是基于 Kubernetes 调度器来执行基于资源的调度。 你应该聚焦于使用基于属性的调度方式，而尽量不要依赖实例类型（例如：应该申请一个 GPU，而不是 g2.2xlarge）。

failure-domain.beta.kubernetes.io/region (deprecated)

参见 topology.kubernetes.io/region.

说明：

从 v1.17 开始，此标签被弃用，取而代之的是 topology.kubernetes.io/region.

failure-domain.beta.kubernetes.io/zone (deprecated)

参见 topology.kubernetes.io/zone.

说明：

从 v1.17 开始，此标签被弃用，取而代之的是 topology.kubernetes.io/zone.

statefulset.kubernetes.io/pod-name

示例：statefulset.kubernetes.io/pod-name=mystatefulset-7

当 StatefulSet 控制器为 StatefulSet 创建 Pod 时，控制平面会在该 Pod 上设置此标签。 标签的值是正在创建的 Pod 的名称。

更多细节请参见 StatefulSet 文章中的 Pod 名称标签。

topology.kubernetes.io/region

示例

topology.kubernetes.io/region=us-east-1

参见 topology.kubernetes.io/zone.

topology.kubernetes.io/zone

示例:

topology.kubernetes.io/zone=us-east-1c

用于：Node, PersistentVolume

Node 场景：kubelet 或外部的 cloud-controller-manager 用 cloudprovider 提供的信息生成此标签。 所以只有在用到 cloudprovider 的场景下，此标签才会被设置。 但如果此标签在你的拓扑中有意义，你也可以考虑在 node 上设置它。

PersistentVolume 场景：拓扑自感知的卷制备程序将在 PersistentVolumes 上自动设置节点亲和性限制。

一个可用区（zone）表示一个逻辑故障域。Kubernetes 集群通常会跨越多个可用区以提高可用性。 虽然可用区的确切定义留给基础设施来决定，但可用区常见的属性包括：可用区内的网络延迟非常低，可用区内的网络通讯没成本，独立于其他可用区的故障域。 例如，一个可用区中的节点可以共享交换机，但不同可用区则不会。

一个地区（region）表示一个更大的域，由一个到多个可用区组成。对于 Kubernetes 来说，跨越多个地区的集群很罕见。 虽然可用区和地区的确切定义留给基础设施来决定，但地区的常见属性包括：地区间比地区内更高的网络延迟，地区间网络流量更高的成本，独立于其他可用区或是地区的故障域。例如，一个地区内的节点可以共享电力基础设施（例如 UPS 或发电机），但不同地区内的节点显然不会。

Kubernetes 对可用区和地区的结构做出一些假设： 1）地区和可用区是层次化的：可用区是地区的严格子集，任何可用区都不能再 2 个地区中出现。 2）可用区名字在地区中独一无二：例如地区 "africa-east-1" 可由可用区 "africa-east-1a" 和 "africa-east-1b" 构成。

你可以安全的假定拓扑类的标签是固定不变的。即使标签严格来说是可变的，但使用者依然可以假定一个节点只有通过销毁、重建的方式，才能在可用区间移动。

Kubernetes 能以多种方式使用这些信息。 例如，调度器自动地尝试将 ReplicaSet 中的 Pod 打散在单可用区集群的不同节点上（以减少节点故障的影响，参见kubernetes.io/hostname）。 在多可用区的集群中，这类打散分布的行为也会应用到可用区（以减少可用区故障的影响）。 做到这一点靠的是 SelectorSpreadPriority。

SelectorSpreadPriority 是一种最大能力分配方法（best effort）。如果集群中的可用区是异构的（例如：不同数量的节点，不同类型的节点，或不同的 Pod 资源需求），这种分配方法可以防止平均分配 Pod 到可用区。如果需要，你可以用同构的可用区（相同数量和类型的节点）来减少潜在的不平衡分布。

调度器（通过 VolumeZonePredicate 的预测）也会保障声明了某卷的 Pod 只能分配到该卷相同的可用区。 卷不支持跨可用区挂载。

如果 PersistentVolumeLabel 不支持给 PersistentVolume 自动打标签，你可以考虑手动加标签（或增加 PersistentVolumeLabel 支持）。 有了 PersistentVolumeLabel，调度器可以防止 Pod 挂载不同可用区中的卷。 如果你的基础架构没有此限制，那你根本就没有必要给卷增加 zone 标签。

node.kubernetes.io/windows-build

示例: node.kubernetes.io/windows-build=10.0.17763

用于：Node

当 kubelet 运行于 Microsoft Windows，它给节点自动打标签，以记录 Windows Server 的版本。

标签值的格式为 "主版本.次版本.构建号"

service.kubernetes.io/headless

示例：service.kubernetes.io/headless=""

用于：Service

在无头（headless）服务的场景下，控制平面为 Endpoint 对象添加此标签。

kubernetes.io/service-name

示例：kubernetes.io/service-name="nginx"

用于：Service

Kubernetes 用此标签区分多个服务。当前仅用于 ELB(Elastic Load Balancer)。

endpointslice.kubernetes.io/managed-by

示例：endpointslice.kubernetes.io/managed-by="controller"

用于：EndpointSlices

此标签用来指向管理 EndpointSlice 的控制器或实体。 此标签的目的是用集群中不同的控制器或实体来管理不同的 EndpointSlice。

endpointslice.kubernetes.io/skip-mirror

示例：endpointslice.kubernetes.io/skip-mirror="true"

用于：Endpoints

此标签在 Endpoints 资源上设为 "true" 指示 EndpointSliceMirroring 控制器不要镜像此 EndpointSlices 资源。

service.kubernetes.io/service-proxy-name

示例：service.kubernetes.io/service-proxy-name="foo-bar"

用于：Service

kube-proxy 把此标签用于客户代理，将服务控制委托给客户代理。

experimental.windows.kubernetes.io/isolation-type

示例：experimental.windows.kubernetes.io/isolation-type: "hyperv"

用于：Pod

此注解用于运行 Hyper-V 隔离的 Windows 容器。 要使用 Hyper-V 隔离特性，并创建 Hyper-V 隔离容器，kubelet 应该用特性门控 HyperVContainer=true 来启动，并且 Pod 应该包含注解 experimental.windows.kubernetes.io/isolation-type=hyperv。

说明： 你只能在单容器 Pod 上设置此注解。

ingressclass.kubernetes.io/is-default-class

示例：ingressclass.kubernetes.io/is-default-class: "true"

用于：IngressClass

当唯一的 IngressClass 资源将此注解的值设为 "true"，没有指定类型的新 Ingress 资源将使用此默认类型。

kubernetes.io/ingress.class (deprecated)

说明：

从 v1.18 开始，此注解被弃用，取而代之的是 spec.ingressClassName。

storageclass.kubernetes.io/is-default-class

示例：storageclass.kubernetes.io/is-default-class=true

用于：StorageClass

当单个的 StorageClass 资源将这个注解设置为 "true" 时，新的持久卷申领（PVC） 资源若未指定类别，将被设定为此默认类别。

alpha.kubernetes.io/provided-node-ip

示例：alpha.kubernetes.io/provided-node-ip: "10.0.0.1"

用于：Node

kubectl 在 Node 上设置此注解，表示它的 IPv4 地址。

当 kubectl 由外部的云供应商启动时，在 Node 上设置此注解，表示由命令行标记(--node-ip)设置的 IP 地址。 cloud-controller-manager 向云供应商验证此 IP 是否有效。

batch.kubernetes.io/job-completion-index

示例：batch.kubernetes.io/job-completion-index: "3"

用于：Pod

kube-controller-manager 中的 Job 控制器给创建使用索引 完成模式 的 Pod 设置此注解。

kubectl.kubernetes.io/default-container

示例：kubectl.kubernetes.io/default-container: "front-end-app"

注解的值是此 Pod 的默认容器名称。 例如，kubectl logs 或 kubectl exec 没有 -c 或 --container 参数时，将使用这个默认的容器。

endpoints.kubernetes.io/over-capacity

示例：endpoints.kubernetes.io/over-capacity:warning

用于：Endpoints

在 Kubernetes 集群 v1.21（或更高版本）中，如果 Endpoint 超过 1000 个，Endpoint 控制器 就会向其添加这个注解。该注解表示 Endpoint 资源已超过容量。

以下列出的污点只能用于 Node

node.kubernetes.io/not-ready

示例：node.kubernetes.io/not-ready:NoExecute

节点控制器通过健康监控来检测节点是否就绪，并据此添加/删除此污点。

node.kubernetes.io/unreachable

示例：node.kubernetes.io/unreachable:NoExecute

如果 NodeCondition 的 Ready 键值为 Unknown，节点控制器将添加污点到 node。

node.kubernetes.io/unschedulable

示例：node.kubernetes.io/unschedulable:NoSchedule

当初始化节点时，添加此污点，来避免竟态的发生。

node.kubernetes.io/memory-pressure

示例：node.kubernetes.io/memory-pressure:NoSchedule

kubelet 依据节点上观测到的 memory.available 和 allocatableMemory.available 来检测内存压力。 用观测值对比 kubelet 设置的阈值，以判断节点状态和污点是否可以被添加/移除。

node.kubernetes.io/disk-pressure

示例：node.kubernetes.io/disk-pressure:NoSchedule

kubelet 依据节点上观测到的 imagefs.available、imagefs.inodesFree、nodefs.available 和 nodefs.inodesFree(仅 Linux) 来判断磁盘压力。 用观测值对比 kubelet 设置的阈值，以确定节点状态和污点是否可以被添加/移除。

node.kubernetes.io/network-unavailable

示例：node.kubernetes.io/network-unavailable:NoSchedule

它初始由 kubectl 设置，云供应商用它来指示对额外网络配置的需求。 仅当云中的路由器配置妥当后，云供应商才会移除此污点。

node.kubernetes.io/pid-pressure

示例：node.kubernetes.io/pid-pressure:NoSchedule

kubelet 检查 /proc/sys/kernel/pid_max 尺寸的 D 值（D-value），以及节点上 Kubernetes 消耗掉的 PID，以获取可用的 PID 数量，此数量可通过指标 pid.available 得到。 然后用此指标对比 kubelet 设置的阈值，以确定节点状态和污点是否可以被添加/移除。

node.cloudprovider.kubernetes.io/uninitialized

示例：node.cloudprovider.kubernetes.io/uninitialized:NoSchedule

当 kubelet 由外部云供应商启动时，在节点上设置此污点以标记节点不可用，直到一个 cloud-controller-manager 控制器初始化此节点之后，才会移除此污点。

node.cloudprovider.kubernetes.io/shutdown

示例：node.cloudprovider.kubernetes.io/shutdown:NoSchedule

如果一个云供应商的节点被指定为关机状态，节点被打上污点 node.cloudprovider.kubernetes.io/shutdown，污点的影响为 NoSchedule。

4 - 访问 API

关于 Kubernetes 如何实现和控制 API 访问的介绍性材料，可阅读 控制 Kubernetes API 的访问。

参考文档：

• 身份认证
  • 使用启动引导令牌来执行身份认证
• 准入控制器
  • 动态准入控制
• 鉴权与授权
  • 基于角色的访问控制
  • 基于属性的访问控制
  • 节点鉴权
  • Webhook 鉴权
• 证书签名请求
  • 包含 CSR 的批复 和证书签名
• 服务账号
  • 开发者指南
  • 管理文档

4.1 - 用户认证

本页提供身份认证有关的概述。

Kubernetes 中的用户

所有 Kubernetes 集群都有两类用户：由 Kubernetes 管理的服务账号和普通用户。

Kubernetes 假定普通用户是由一个与集群无关的服务通过以下方式之一进行管理的：

• 负责分发私钥的管理员
• 类似 Keystone 或者 Google Accounts 这类用户数据库
• 包含用户名和密码列表的文件

有鉴于此，Kubernetes 并不包含用来代表普通用户账号的对象。 普通用户的信息无法通过 API 调用添加到集群中。

尽管无法通过 API 调用来添加普通用户，Kubernetes 仍然认为能够提供由集群的证书 机构签名的合法证书的用户是通过身份认证的用户。基于这样的配置，Kubernetes 使用证书中的 'subject' 的通用名称（Common Name）字段（例如，"/CN=bob"）来 确定用户名。接下来，基于角色访问控制（RBAC）子系统会确定用户是否有权针对 某资源执行特定的操作。进一步的细节可参阅 证书请求 下普通用户主题。

与此不同，服务账号是 Kubernetes API 所管理的用户。它们被绑定到特定的名字空间， 或者由 API 服务器自动创建，或者通过 API 调用创建。服务账号与一组以 Secret 保存 的凭据相关，这些凭据会被挂载到 Pod 中，从而允许集群内的进程访问 Kubernetes API。

API 请求则或者与某普通用户相关联，或者与某服务账号相关联，亦或者被视作 匿名请求。这意味着集群内外的每个进程在向 API 服务器发起 请求时都必须通过身份认证，否则会被视作匿名用户。这里的进程可以是在某工作站上 输入 kubectl 命令的操作人员，也可以是节点上的 kubelet 组件，还可以是控制面 的成员。

身份认证策略

Kubernetes 使用身份认证插件利用客户端证书、持有者令牌（Bearer Token）、身份认证代理（Proxy） 或者 HTTP 基本认证机制来认证 API 请求的身份。HTTP 请求发给 API 服务器时， 插件会将以下属性关联到请求本身：

• 用户名：用来辩识最终用户的字符串。常见的值可以是 kube-admin 或 jane@example.com。
• 用户 ID：用来辩识最终用户的字符串，旨在比用户名有更好的一致性和唯一性。
• 用户组：取值为一组字符串，其中各个字符串用来标明用户是某个命名的用户逻辑集合的成员。 常见的值可能是 system:masters 或者 devops-team 等。
• 附加字段：一组额外的键-值映射，键是字符串，值是一组字符串；用来保存一些鉴权组件可能 觉得有用的额外信息。

所有（属性）值对于身份认证系统而言都是不透明的，只有被 鉴权组件 解释过之后才有意义。

你可以同时启用多种身份认证方法，并且你通常会至少使用两种方法：

• 针对服务账号使用服务账号令牌
• 至少另外一种方法对用户的身份进行认证

当集群中启用了多个身份认证模块时，第一个成功地对请求完成身份认证的模块会 直接做出评估决定。API 服务器并不保证身份认证模块的运行顺序。

对于所有通过身份认证的用户，system:authenticated 组都会被添加到其组列表中。

与其它身份认证协议（LDAP、SAML、Kerberos、X509 的替代模式等等）都可以通过 使用一个身份认证代理或 身份认证 Webhoook来实现。

X509 客户证书

通过给 API 服务器传递 --client-ca-file=SOMEFILE 选项，就可以启动客户端证书身份认证。 所引用的文件必须包含一个或者多个证书机构，用来验证向 API 服务器提供的客户端证书。 如果提供了客户端证书并且证书被验证通过，则 subject 中的公共名称（Common Name）就被 作为请求的用户名。 自 Kubernetes 1.4 开始，客户端证书还可以通过证书的 organization 字段标明用户的组成员信息。 要包含用户的多个组成员信息，可以在证书种包含多个 organization 字段。

例如，使用 openssl 命令行工具生成一个证书签名请求：

openssl req -new -key jbeda.pem -out jbeda-csr.pem -subj "/CN=jbeda/O=app1/O=app2"

此命令将使用用户名 jbeda 生成一个证书签名请求（CSR），且该用户属于 "app" 和 "app2" 两个用户组。

参阅管理证书了解如何生成客户端证书。

静态令牌文件

当 API 服务器的命令行设置了 --token-auth-file=SOMEFILE 选项时，会从文件中 读取持有者令牌。目前，令牌会长期有效，并且在不重启 API 服务器的情况下 无法更改令牌列表。

令牌文件是一个 CSV 文件，包含至少 3 个列：令牌、用户名和用户的 UID。 其余列被视为可选的组名。

说明：

如果要设置的组名不止一个，则对应的列必须用双引号括起来，例如

token,user,uid,"group1,group2,group3"

在请求中放入持有者令牌

当使用持有者令牌来对某 HTTP 客户端执行身份认证时，API 服务器希望看到 一个名为 Authorization 的 HTTP 头，其值格式为 Bearer THETOKEN。 持有者令牌必须是一个可以放入 HTTP 头部值字段的字符序列，至多可使用 HTTP 的编码和引用机制。 例如：如果持有者令牌为 31ada4fd-adec-460c-809a-9e56ceb75269，则其 出现在 HTTP 头部时如下所示：

Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269

启动引导令牌

为了支持平滑地启动引导新的集群，Kubernetes 包含了一种动态管理的持有者令牌类型， 称作 启动引导令牌（Bootstrap Token）。 这些令牌以 Secret 的形式保存在 kube-system 名字空间中，可以被动态管理和创建。 控制器管理器包含的 TokenCleaner 控制器能够在启动引导令牌过期时将其删除。

这些令牌的格式为 [a-z0-9]{6}.[a-z0-9]{16}。第一个部分是令牌的 ID；第二个部分 是令牌的 Secret。你可以用如下所示的方式来在 HTTP 头部设置令牌：

Authorization: Bearer 781292.db7bc3a58fc5f07e

你必须在 API 服务器上设置 --enable-bootstrap-token-auth 标志来启用基于启动 引导令牌的身份认证组件。 你必须通过控制器管理器的 --controllers 标志来启用 TokenCleaner 控制器； 这可以通过类似 --controllers=*,tokencleaner 这种设置来做到。 如果你使用 kubeadm 来启动引导新的集群，该工具会帮你完成这些设置。

身份认证组件的认证结果为 system:bootstrap:<令牌 ID>，该用户属于 system:bootstrappers 用户组。 这里的用户名和组设置都是有意设计成这样，其目的是阻止用户在启动引导集群之后 继续使用这些令牌。 这里的用户名和组名可以用来（并且已经被 kubeadm 用来）构造合适的鉴权 策略，以完成启动引导新集群的工作。

请参阅启动引导令牌 以了解关于启动引导令牌身份认证组件与控制器的更深入的信息，以及如何使用 kubeadm 来管理这些令牌。

服务账号令牌

服务账号（Service Account）是一种自动被启用的用户认证机制，使用经过签名的 持有者令牌来验证请求。该插件可接受两个可选参数：

• --service-account-key-file 一个包含用来为持有者令牌签名的 PEM 编码密钥。 若未指定，则使用 API 服务器的 TLS 私钥。
• --service-account-lookup 如果启用，则从 API 删除的令牌会被回收。

服务账号通常由 API 服务器自动创建并通过 ServiceAccount 准入控制器 关联到集群中运行的 Pod 上。 持有者令牌会挂载到 Pod 中可预知的位置，允许集群内进程与 API 服务器通信。 服务账号也可以使用 Pod 规约的 serviceAccountName 字段显式地关联到 Pod 上。

说明： serviceAccountName 通常会被忽略，因为关联关系是自动建立的。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: default
spec:
  replicas: 3
  template:
    metadata:
    # ...
    spec:
      serviceAccountName: bob-the-bot
      containers:
      - name: nginx
        image: nginx:1.14.2

在集群外部使用服务账号持有者令牌也是完全合法的，且可用来为长时间运行的、需要与 Kubernetes API 服务器通信的任务创建标识。要手动创建服务账号，可以使用 kubectl create serviceaccount <名称> 命令。此命令会在当前的名字空间中生成一个 服务账号和一个与之关联的 Secret。

kubectl create serviceaccount jenkins

serviceaccount/jenkins created

查验相关联的 Secret：

kubectl get serviceaccounts jenkins -o yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  # ...
secrets:
- name: jenkins-token-1yvwg

所创建的 Secret 中会保存 API 服务器的公开的 CA 证书和一个已签名的 JSON Web 令牌（JWT）。

kubectl get secret jenkins-token-1yvwg -o yaml

apiVersion: v1
data:
  ca.crt: <Base64 编码的 API 服务器 CA>
  namespace: ZGVmYXVsdA==
  token: <Base64 编码的持有者令牌>
kind: Secret
metadata:
  # ...
type: kubernetes.io/service-account-token

说明： 字段值是按 Base64 编码的，这是因为 Secret 数据总是采用 Base64 编码来存储。

已签名的 JWT 可以用作持有者令牌，并将被认证为所给的服务账号。 关于如何在请求中包含令牌，请参阅前文。 通常，这些 Secret 数据会被挂载到 Pod 中以便集群内访问 API 服务器时使用， 不过也可以在集群外部使用。

服务账号被身份认证后，所确定的用户名为 system:serviceaccount:<名字空间>:<服务账号>， 并被分配到用户组 system:serviceaccounts 和 system:serviceaccounts:<名字空间>。

警告：由于服务账号令牌保存在 Secret 对象中，任何能够读取这些 Secret 的用户 都可以被认证为对应的服务账号。在为用户授予访问服务账号的权限时，以及对 Secret 的读权限时，要格外小心。

OpenID Connect（OIDC）令牌

OpenID Connect 是一种 OAuth2 认证方式， 被某些 OAuth2 提供者支持，例如 Azure 活动目录、Salesforce 和 Google。 协议对 OAuth2 的主要扩充体现在有一个附加字段会和访问令牌一起返回， 这一字段称作 ID Token（ID 令牌）。 ID 令牌是一种由服务器签名的 JSON Web 令牌（JWT），其中包含一些可预知的字段， 例如用户的邮箱地址，

要识别用户，身份认证组件使用 OAuth2 令牌响应 中的 id_token（而非 access_token）作为持有者令牌。 关于如何在请求中设置令牌，可参见前文。

1. 登录到你的身份服务（Identity Provider）
2. 你的身份服务将为你提供 access_token、id_token 和 refresh_token
3. 在使用 kubectl 时，将 id_token 设置为 --token 标志值，或者将其直接添加到 kubeconfig 中
4. kubectl 将你的 id_token 放到一个称作 Authorization 的头部，发送给 API 服务器
5. API 服务器将负责通过检查配置中引用的证书来确认 JWT 的签名是合法的
6. 检查确认 id_token 尚未过期
7. 确认用户有权限执行操作
8. 鉴权成功之后，API 服务器向 kubectl 返回响应
9. kubectl 向用户提供反馈信息

由于用来验证你是谁的所有数据都在 id_token 中，Kubernetes 不需要再去联系 身份服务。在一个所有请求都是无状态请求的模型中，这一工作方式可以使得身份认证 的解决方案更容易处理大规模请求。不过，此访问也有一些挑战：

1. Kubernetes 没有提供用来触发身份认证过程的 "Web 界面"。 因为不存在用来收集用户凭据的浏览器或用户接口，你必须自己先行完成 对身份服务的认证过程。
2. id_token 令牌不可收回。因其属性类似于证书，其生命期一般很短（只有几分钟）， 所以，每隔几分钟就要获得一个新的令牌这件事可能很让人头疼。
3. 如果不使用 kubectl proxy 命令或者一个能够注入 id_token 的反向代理， 向 Kubernetes 控制面板执行身份认证是很困难的。

配置 API 服务器

要启用此插件，须在 API 服务器上配置以下标志：

很重要的一点是，API 服务器并非一个 OAuth2 客户端，相反，它只能被配置为 信任某一个令牌发放者。这使得使用公共服务（如 Google）的用户可以不信任发放给 第三方的凭据。 如果管理员希望使用多个 OAuth 客户端，他们应该研究一下那些支持 azp （Authorized Party，被授权方）申领的服务。 azp 是一种允许某客户端代替另一客户端发放令牌的机制。

Kubernetes 并未提供 OpenID Connect 的身份服务。 你可以使用现有的公共的 OpenID Connect 身份服务（例如 Google 或者 其他服务）。 或者，你也可以选择自己运行一个身份服务，例如 CoreOS dex、 Keycloak、 CloudFoundry UAA 或者 Tremolo Security 的 OpenUnison。

要在 Kubernetes 环境中使用某身份服务，该服务必须：

1. 支持 OpenID connect 发现； 但事实上并非所有服务都具备此能力
2. 运行 TLS 协议且所使用的加密组件都未过时
3. 拥有由 CA 签名的证书（即使 CA 不是商业 CA 或者是自签名的 CA 也可以）

关于上述第三条需求，即要求具备 CA 签名的证书，有一些额外的注意事项。 如果你部署了自己的身份服务，而不是使用云厂商（如 Google 或 Microsoft）所提供的服务， 你必须对身份服务的 Web 服务器证书进行签名，签名所用证书的 CA 标志要设置为 TRUE，即使用的是自签名证书。这是因为 GoLang 的 TLS 客户端实现对证书验证 标准方面有非常严格的要求。如果你手头没有现成的 CA 证书，可以使用 CoreOS 团队所开发的这个脚本 来创建一个简单的 CA 和被签了名的证书与密钥对。 或者你也可以使用 这个类似的脚本， 生成一个合法期更长、密钥尺寸更大的 SHA256 证书。

特定系统的安装指令：

• UAA
• Dex
• OpenUnison

使用 kubectl

选项一 - OIDC 身份认证组件

第一种方案是使用 kubectl 的 oidc 身份认证组件，该组件将 id_token 设置 为所有请求的持有者令牌，并且在令牌过期时自动刷新。在你登录到你的身份服务之后， 可以使用 kubectl 来添加你的 id_token、refresh_token、client_id 和 client_secret，以配置该插件。

如果服务在其刷新令牌响应中不包含 id_token，则此插件无法支持该服务。 这时你应该考虑下面的选项二。

kubectl config set-credentials USER_NAME \
   --auth-provider=oidc \
   --auth-provider-arg=idp-issuer-url=( issuer url ) \
   --auth-provider-arg=client-id=( your client id ) \
   --auth-provider-arg=client-secret=( your client secret ) \
   --auth-provider-arg=refresh-token=( your refresh token ) \
   --auth-provider-arg=idp-certificate-authority=( path to your ca certificate ) \
   --auth-provider-arg=id-token=( your id_token )

作为示例，在完成对你的身份服务的身份认证之后，运行下面的命令：

kubectl config set-credentials mmosley  \
        --auth-provider=oidc  \
        --auth-provider-arg=idp-issuer-url=https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP  \
        --auth-provider-arg=client-id=kubernetes  \
        --auth-provider-arg=client-secret=1db158f6-177d-4d9c-8a8b-d36869918ec5  \
        --auth-provider-arg=refresh-token=q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXqHega4GAXlF+ma+vmYpFcHe5eZR+slBFpZKtQA= \
        --auth-provider-arg=idp-certificate-authority=/root/ca.pem \
        --auth-provider-arg=id-token=eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw

此操作会生成以下配置：

users:
- name: mmosley
  user:
    auth-provider:
      config:
        client-id: kubernetes
        client-secret: 1db158f6-177d-4d9c-8a8b-d36869918ec5
        id-token: eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw
        idp-certificate-authority: /root/ca.pem
        idp-issuer-url: https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP
        refresh-token: q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXq
      name: oidc

当你的 id_token 过期时，kubectl 会尝试使用你的 refresh_token 来刷新你的 id_token，并且在 client_secret 中存放 refresh_token 的新值，同时把 id_token 的新值写入到 .kube/config 文件中。

选项二 - 使用 --token 选项

kubectl 命令允许你使用 --token 选项传递一个令牌。 你可以将 id_token 的内容复制粘贴过来，作为此标志的取值：

kubectl --token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL21sYi50cmVtb2xvLmxhbjo4MDQzL2F1dGgvaWRwL29pZGMiLCJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNDc0NTk2NjY5LCJqdGkiOiI2RDUzNXoxUEpFNjJOR3QxaWVyYm9RIiwiaWF0IjoxNDc0NTk2MzY5LCJuYmYiOjE0NzQ1OTYyNDksInN1YiI6Im13aW5kdSIsInVzZXJfcm9sZSI6WyJ1c2VycyIsIm5ldy1uYW1lc3BhY2Utdmlld2VyIl0sImVtYWlsIjoibXdpbmR1QG5vbW9yZWplZGkuY29tIn0.f2As579n9VNoaKzoF-dOQGmXkFKf1FMyNV0-va_B63jn-_n9LGSCca_6IVMP8pO-Zb4KvRqGyTP0r3HkHxYy5c81AnIh8ijarruczl-TK_yF5akjSTHFZD-0gRzlevBDiH8Q79NAr-ky0P4iIXS8lY9Vnjch5MF74Zx0c3alKJHJUnnpjIACByfF2SCaYzbWFMUNat-K1PaUk5-ujMBG7yYnr95xD-63n8CO8teGUAAEMx6zRjzfhnhbzX-ajwZLGwGUBT4WqjMs70-6a7_8gZmLZb2az1cZynkFRj2BaCkVT3A2RrjeEwZEtGXlMqKJ1_I2ulrOVsYx01_yD35-rw get nodes

Webhook 令牌身份认证

Webhook 身份认证是一种用来验证持有者令牌的回调机制。

• --authentication-token-webhook-config-file 指向一个配置文件，其中描述 如何访问远程的 Webhook 服务。
• --authentication-token-webhook-cache-ttl 用来设定身份认证决定的缓存时间。 默认时长为 2 分钟。

配置文件使用 kubeconfig 文件的格式。文件中，clusters 指代远程服务，users 指代远程 API 服务 Webhook。下面是一个例子：

# Kubernetes API 版本
apiVersion: v1
# API 对象类别
kind: Config
# clusters 指代远程服务
clusters:
  - name: name-of-remote-authn-service
    cluster:
      certificate-authority: /path/to/ca.pem         # 用来验证远程服务的 CA
      server: https://authn.example.com/authenticate # 要查询的远程服务 URL。必须使用 'https'。

# users 指代 API 服务的 Webhook 配置
users:
  - name: name-of-api-server
    user:
      client-certificate: /path/to/cert.pem # Webhook 插件要使用的证书
      client-key: /path/to/key.pem          # 与证书匹配的密钥

# kubeconfig 文件需要一个上下文（Context），此上下文用于本 API 服务器
current-context: webhook
contexts:
- context:
    cluster: name-of-remote-authn-service
    user: name-of-api-sever
  name: webhook

当客户端尝试在 API 服务器上使用持有者令牌完成身份认证（ 如前所述）时， 身份认证 Webhook 会用 POST 请求发送一个 JSON 序列化的对象到远程服务。 该对象是 authentication.k8s.io/v1beta1 组的 TokenReview 对象， 其中包含持有者令牌。 Kubernetes 不会强制请求提供此 HTTP 头部。

要注意的是，Webhook API 对象和其他 Kubernetes API 对象一样，也要受到同一 版本兼容规则约束。 实现者要了解对 Beta 阶段对象的兼容性承诺，并检查请求的 apiVersion 字段， 以确保数据结构能够正常反序列化解析。此外，API 服务器必须启用 authentication.k8s.io/v1beta1 API 扩展组 （--runtime-config=authentication.k8s.io/v1beta1=true）。

POST 请求的 Body 部分将是如下格式：

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "spec": {
    "token": "<持有者令牌>"
  }
}

远程服务应该会填充请求的 status 字段，以标明登录操作是否成功。 响应的 Body 中的 spec 字段会被忽略，因此可以省略。 如果持有者令牌验证成功，应该返回如下所示的响应：

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": true,
    "user": {
      "username": "janedoe@example.com",
      "uid": "42",
      "groups": [
        "developers",
        "qa"
      ],
      "extra": {
        "extrafield1": [
          "extravalue1",
          "extravalue2"
        ]
      }
    }
  }
}

而不成功的请求会返回：

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": false
  }
}

HTTP 状态码可用来提供进一步的错误语境信息。

身份认证代理

API 服务器可以配置成从请求的头部字段值（如 X-Remote-User）中辩识用户。 这一设计是用来与某身份认证代理一起使用 API 服务器，代理负责设置请求的头部字段值。

• --requestheader-username-headers 必需字段，大小写不敏感。用来设置要获得用户身份所要检查的头部字段名称列表（有序）。第一个包含数值的字段会被用来提取用户名。
• --requestheader-group-headers 可选字段，在 Kubernetes 1.6 版本以后支持，大小写不敏感。 建议设置为 "X-Remote-Group"。用来指定一组头部字段名称列表，以供检查用户所属的组名称。 所找到的全部头部字段的取值都会被用作用户组名。
• --requestheader-extra-headers-prefix 可选字段，在 Kubernetes 1.6 版本以后支持，大小写不敏感。 建议设置为 "X-Remote-Extra-"。用来设置一个头部字段的前缀字符串，API 服务器会基于所给 前缀来查找与用户有关的一些额外信息。这些额外信息通常用于所配置的鉴权插件。 API 服务器会将与所给前缀匹配的头部字段过滤出来，去掉其前缀部分，将剩余部分 转换为小写字符串并在必要时执行百分号解码 后，构造新的附加信息字段键名。原来的头部字段值直接作为附加信息字段的值。

说明： 在 1.13.3 版本之前（包括 1.10.7、1.9.11），附加字段的键名只能包含 HTTP 头部标签的合法字符。

例如，使用下面的配置：

--requestheader-username-headers=X-Remote-User
--requestheader-group-headers=X-Remote-Group
--requestheader-extra-headers-prefix=X-Remote-Extra-

针对所收到的如下请求：

GET / HTTP/1.1
X-Remote-User: fido
X-Remote-Group: dogs
X-Remote-Group: dachshunds
X-Remote-Extra-Acme.com%2Fproject: some-project
X-Remote-Extra-Scopes: openid
X-Remote-Extra-Scopes: profile

会生成下面的用户信息：

name: fido
groups:
- dogs
- dachshunds
extra:
  acme.com/project:
  - some-project
  scopes:
  - openid
  - profile

为了防范头部信息侦听，在请求中的头部字段被检视之前， 身份认证代理需要向 API 服务器提供一份合法的客户端证书， 供后者使用所给的 CA 来执行验证。 警告：不要 在不同的上下文中复用 CA 证书，除非你清楚这样做的风险是什么以及 应如何保护 CA 用法的机制。

• --requestheader-client-ca-file 必需字段，给出 PEM 编码的证书包。 在检查请求的头部字段以提取用户名信息之前，必须提供一个合法的客户端证书， 且该证书要能够被所给文件中的机构所验证。
• --requestheader-allowed-names 可选字段，用来给出一组公共名称（CN）。 如果此标志被设置，则在检视请求中的头部以提取用户信息之前，必须提供 包含此列表中所给的 CN 名的、合法的客户端证书。

匿名请求

启用匿名请求支持之后，如果请求没有被已配置的其他身份认证方法拒绝，则被视作 匿名请求（Anonymous Requests）。这类请求获得用户名 system:anonymous 和 对应的用户组 system:unauthenticated。

例如，在一个配置了令牌身份认证且启用了匿名访问的服务器上，如果请求提供了非法的 持有者令牌，则会返回 401 Unauthorized 错误。 如果请求没有提供持有者令牌，则被视为匿名请求。

在 1.5.1-1.5.x 版本中，匿名访问默认情况下是被禁用的，可以通过为 API 服务器设定 --anonymous-auth=true 来启用。

在 1.6 及之后版本中，如果所使用的鉴权模式不是 AlwaysAllow，则匿名访问默认是被启用的。 从 1.6 版本开始，ABAC 和 RBAC 鉴权模块要求对 system:anonymous 用户或者 system:unauthenticated 用户组执行显式的权限判定，所以之前的为 * 用户或 * 用户组赋予访问权限的策略规则都不再包含匿名用户。

用户伪装

一个用户可以通过伪装（Impersonation）头部字段来以另一个用户的身份执行操作。 使用这一能力，你可以手动重载请求被身份认证所识别出来的用户信息。 例如，管理员可以使用这一功能特性来临时伪装成另一个用户，查看请求是否被拒绝， 从而调试鉴权策略中的问题，

带伪装的请求首先会被身份认证识别为发出请求的用户，之后会切换到使用被伪装的用户 的用户信息。

• 用户发起 API 调用时 同时 提供自身的凭据和伪装头部字段信息
• API 服务器对用户执行身份认证
• API 服务器确认通过认证的用户具有伪装特权
• 请求用户的信息被替换成伪装字段的值
• 评估请求，鉴权组件针对所伪装的用户信息执行操作

以下 HTTP 头部字段可用来执行伪装请求：

• Impersonate-User：要伪装成的用户名
• Impersonate-Group：要伪装成的用户组名。可以多次指定以设置多个用户组。 可选字段；要求 "Impersonate-User" 必须被设置。
• Impersonate-Extra-<附加名称>：一个动态的头部字段，用来设置与用户相关的附加字段。 此字段可选；要求 "Impersonate-User" 被设置。为了能够以一致的形式保留， <附加名称>部分必须是小写字符，如果有任何字符不是 合法的 HTTP 头部标签字符， 则必须是 utf8 字符，且转换为百分号编码。

说明： 在 1.11.3 版本之前（以及 1.10.7、1.9.11），<附加名称> 只能包含 合法的 HTTP 标签字符。

头部字段集合的示例：

Impersonate-User: jane.doe@example.com
Impersonate-Group: developers
Impersonate-Group: admins
Impersonate-Extra-dn: cn=jane,ou=engineers,dc=example,dc=com
Impersonate-Extra-acme.com%2Fproject: some-project
Impersonate-Extra-scopes: view
Impersonate-Extra-scopes: development

在使用 kubectl 时，可以使用 --as 标志来配置 Impersonate-User 头部字段值， 使用 --as-group 标志配置 Impersonate-Group 头部字段值。

kubectl drain mynode

Error from server (Forbidden): User "clark" cannot get nodes at the cluster scope. (get nodes mynode)

设置 --as 和 --as-group 标志：

kubectl drain mynode --as=superman --as-group=system:masters

node/mynode cordoned
node/mynode drained

要伪装成某个用户、某个组或者设置附加字段，执行伪装操作的用户必须具有对所伪装的 类别（“user”、“group” 等）执行 “impersonate” 动词操作的能力。 对于启用了 RBAC 鉴权插件的集群，下面的 ClusterRole 封装了设置用户和组伪装字段 所需的规则：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: impersonator
rules:
- apiGroups: [""]
  resources: ["users", "groups", "serviceaccounts"]
  verbs: ["impersonate"]

附加字段会被作为 userextras 资源的子资源来执行权限评估。 如果要允许用户为附加字段 “scopes” 设置伪装头部，该用户需要被授予以下规则：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: scopes-impersonator
rules:
# 可以设置 "Impersonate-Extra-scopes" 头部
- apiGroups: ["authentication.k8s.io"]
  resources: ["userextras/scopes"]
  verbs: ["impersonate"]

你也可以通过约束资源可能对应的 resourceNames 限制伪装头部的取值：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: limited-impersonator
rules:
# 可以伪装成用户 "jane.doe@example.com"
- apiGroups: [""]
  resources: ["users"]
  verbs: ["impersonate"]
  resourceNames: ["jane.doe@example.com"]

# 可以伪装成用户组 "developers" 和 "admins"
- apiGroups: [""]
  resources: ["groups"]
  verbs: ["impersonate"]
  resourceNames: ["developers","admins"]

# 可以将附加字段 "scopes" 伪装成 "view" 和 "development"
- apiGroups: ["authentication.k8s.io"]
  resources: ["userextras/scopes"]
  verbs: ["impersonate"]
  resourceNames: ["view", "development"]

client-go 凭据插件

k8s.io/client-go 及使用它的工具（如 kubectl 和 kubelet）可以执行某个外部 命令来获得用户的凭据信息。

这一特性的目的是便于客户端与 k8s.io/client-go 并不支持的身份认证协议（LDAP、 Kerberos、OAuth2、SAML 等）继承。 插件实现特定于协议的逻辑，之后返回不透明的凭据以供使用。 几乎所有的凭据插件使用场景中都需要在服务器端存在一个支持 Webhook 令牌身份认证组件的模块， 负责解析客户端插件所生成的凭据格式。

示例应用场景

在一个假想的应用场景中，某组织运行这一个外部的服务，能够将特定用户的已签名的 令牌转换成 LDAP 凭据。此服务还能够对 Webhook 令牌身份认证组件的请求做出响应以 验证所提供的令牌。用户需要在自己的工作站上安装一个凭据插件。

要对 API 服务器认证身份时：

• 用户发出 kubectl 命令。
• 凭据插件提示用户输入 LDAP 凭据，并与外部服务交互，获得令牌。
• 凭据插件将令牌返回该 client-go，后者将其用作持有者令牌提交给 API 服务器。
• API 服务器使用Webhook 令牌身份认证组件向 外部服务发出 TokenReview 请求。
• 外部服务检查令牌上的签名，返回用户的用户名和用户组信息。

配置

凭据插件通过 kubectl 配置文件 来作为 user 字段的一部分设置。

apiVersion: v1
kind: Config
users:
- name: my-user
  user:
    exec:
      # 要执行的命令。必需。
      command: "example-client-go-exec-plugin"

      # 解析 ExecCredentials 资源时使用的 API 版本。必需。
      #
      # 插件返回的 API 版本必需与这里列出的版本匹配。
      #
      # 要与支持多个版本的工具（如 client.authentication.k8sio/v1alpha1）集成，
      # 可以设置一个环境变量或者向工具传递一个参数标明 exec 插件所期望的版本。
      apiVersion: "client.authentication.k8s.io/v1beta1"

      # 执行此插件时要设置的环境变量。可选字段。
      env:
      - name: "FOO"
        value: "bar"

      # 执行插件时要传递的参数。可选字段。
      args:
      - "arg1"
      - "arg2"

      # 当可执行文件不存在时显示给用户的文本。可选的。
      installHint: |
        需要 example-client-go-exec-plugin 来在当前集群上执行身份认证。可以通过以下命令安装：

        MacOS: brew install example-client-go-exec-plugin

        Ubuntu: apt-get install example-client-go-exec-plugin

        Fedora: dnf install example-client-go-exec-plugin

        ...        

      # 是否使用 KUBERNETES_EXEC_INFO 环境变量的一部分向这个 exec 插件
      # 提供集群信息（可能包含非常大的 CA 数据）
      provideClusterInfo: true
clusters:
- name: my-cluster
  cluster:
    server: "https://172.17.4.100:6443"
    certificate-authority: "/etc/kubernetes/ca.pem"
    extensions:
    - name: client.authentication.k8s.io/exec # 为每个集群 exec 配置保留的扩展名
      extension:
        arbitrary: config
        this: 在设置 provideClusterInfo 时可通过环境变量 KUBERNETES_EXEC_INFO 指定
        you: ["can", "put", "anything", "here"]
contexts:
- name: my-cluster
  context:
    cluster: my-cluster
    user: my-user
current-context: my-cluster

解析相对命令路径时，kubectl 将其视为与配置文件比较而言的相对路径。 如果 KUBECONFIG 被设置为 /home/jane/kubeconfig，而 exec 命令为 ./bin/example-client-go-exec-plugin，则要执行的可执行文件为 /home/jane/bin/example-client-go-exec-plugin。

- name: my-user
  user:
    exec:
      # 对 kubeconfig 目录而言的相对路径
      command: "./bin/example-client-go-exec-plugin"
      apiVersion: "client.authentication.k8s.io/v1beta1"

输出和输出格式

所执行的命令会在 stdout 打印 ExecCredential 对象。 k8s.io/client-go 使用 status 中返回的凭据信息向 Kubernetes API 服务器 执行身份认证。

在交互式会话中运行时，stdin 是直接暴露给插件使用的。 插件应该使用 TTY check 来确定是否适合用交互方式请求用户输入。

与使用持有者令牌凭据，插件在 ExecCredential 的状态中返回一个令牌：

{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "status": {
    "token": "my-bearer-token"
  }
}

另一种方案是，返回 PEM 编码的客户端证书和密钥，以便执行 TLS 客户端身份认证。 如果插件在后续调用中返回了不同的证书或密钥，k8s.io/client-go 会终止其与服务器的连接，从而强制执行新的 TLS 握手过程。

如果指定了这种方式，则 clientKeyData 和 clientCertificateData 字段都必需存在。

clientCertificateData 字段可能包含一些要发送给服务器的中间证书（Intermediate Certificates）。

{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "status": {
    "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

作为一种可选方案，响应中还可以包含以 RFC3339 时间戳格式给出的证书到期时间。 证书到期时间的有无会有如下影响：

• 如果响应中包含了到期时间，持有者令牌和 TLS 凭据会被缓存，直到到期期限到来、 或者服务器返回 401 HTTP 状态码，或者进程退出。
• 如果未指定到期时间，则持有者令牌和 TLS 凭据会被缓存，直到服务器返回 401 HTTP 状态码或者进程退出。

{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "status": {
    "token": "my-bearer-token",
    "expirationTimestamp": "2018-03-05T17:30:20-08:00"
  }
}

调用此插件时可以选择性地设置环境变量 KUBERNETES_EXEC_INFO。 该变量包含了此插件获取凭据所针对的集群信息。此信息可用于执行群集特定的凭据获取逻辑。 为了启用此行为，必须在 kubeconfig 中的 exec user 字段上设置provideClusterInfo字段。 下面是上述 KUBERNETES_EXEC_INFO 环境变量的示例。

{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "spec": {
    "cluster": {
      "server": "https://172.17.4.100:6443",
      "certificate-authority-data": "LS0t...",
      "config": {
        "arbitrary": "config",
        "this": "在设置 provideClusterInfo 时可通过环境变量 KUBERNETES_EXEC_INFO 指定",
        "you": ["can", "put", "anything", "here"]
      }
    }
  }
}

4.2 - 使用启动引导令牌（Bootstrap Tokens）认证

启动引导令牌是一种简单的持有者令牌（Bearer Token），这种令牌是在新建集群 或者在现有集群中添加新节点时使用的。 它被设计成能够支持 kubeadm， 但是也可以被用在其他的案例中以便用户在不使用 kubeadm 的情况下启动集群。 它也被设计成可以通过 RBAC 策略，结合 Kubelet TLS 启动引导 系统进行工作。

启动引导令牌被定义成一个特定类型的 Secret（bootstrap.kubernetes.io/token）， 并存在于 kube-system 名字空间中。 这些 Secret 会被 API 服务器上的启动引导认证组件（Bootstrap Authenticator）读取。 控制器管理器中的控制器 TokenCleaner 能够删除过期的令牌。 这些令牌也被用来在节点发现的过程中会使用的一个特殊的 ConfigMap 对象。 BootstrapSigner 控制器也会使用这一 ConfigMap。

令牌格式

启动引导令牌使用 abcdef.0123456789abcdef 的形式。 更加规范地说，它们必须符合正则表达式 [a-z0-9]{6}\.[a-z0-9]{16}。

令牌的第一部分是 “Token ID”，它是一种公开信息，用于引用令牌并确保不会 泄露认证所使用的秘密信息。 第二部分是“令牌秘密（Token Secret）”，它应该被共享给受信的第三方。

启用启动引导令牌

启用启动引导令牌身份认证

启动引导令牌认证组件可以通过 API 服务器上的如下标志启用：

--enable-bootstrap-token-auth

启动引导令牌被启用后，可以作为持有者令牌的凭据，用于 API 服务器请求的身份认证。

Authorization: Bearer 07401b.f395accd246ae52d

令牌认证为用户名 system:bootstrap:<token id> 并且是组 system:bootstrappers 的成员。额外的组信息可以通过令牌的 Secret 来设置。

过期的令牌可以通过启用控制器管理器中的 tokencleaner 控制器来删除。

启动引导令牌的 Secret 格式

每个合法的令牌背后对应着 kube-system 名字空间中的某个 Secret 对象。 你可以从 这里. 找到完整设计文档。

这是 Secret 看起来的样子。

apiVersion: v1
kind: Secret
metadata:
  # name 必须是 "bootstrap-token-<token id>" 格式的
  name: bootstrap-token-07401b
  namespace: kube-system

# type 必须是 'bootstrap.kubernetes.io/token'
type: bootstrap.kubernetes.io/token
stringData:
  # 供人阅读的描述，可选。
  description: "The default bootstrap token generated by 'kubeadm init'."

  # 令牌 ID 和秘密信息，必需。
  token-id: 07401b
  token-secret: base64(f395accd246ae52d)

  # 可选的过期时间字段
  expiration: "2017-03-10T03:22:11Z"
  # 允许的用法
  usage-bootstrap-authentication: "true"
  usage-bootstrap-signing: "true"

  # 令牌要认证为的额外组，必须以 "system:bootstrappers:" 开头
  auth-extra-groups: system:bootstrappers:worker,system:bootstrappers:ingress

Secret 的类型必须是 bootstrap.kubernetes.io/token，而且名字必须是 bootstrap-token-<token id>。 令牌必须存在于 kube-system 名字空间中。

usage-bootstrap-* 成员表明这个 Secret 的用途。启用时，值必须设置为 true。

• usage-bootstrap-authentication 表示令牌可以作为持有者令牌用于 API 服务器的身份认证。
• usage-bootstrap-signing 表示令牌可被用于 cluster-info ConfigMap 的签名， 就像下面描述的那样。

expiration 字段控制令牌的失效期。过期的令牌在用于身份认证时会被拒绝，在用于 ConfigMap 签名时会被忽略。 过期时间值是遵循 RFC3339 进行编码的 UTC 时间。 启用 TokenCleaner 控制器会自动删除过期的令牌。

使用 kubeadm 管理令牌

你可以使用 kubeadm 工具管理运行中集群上的令牌。 参见 kubeadm token 文档 以了解详细信息。

ConfigMap 签名

除了身份认证，令牌还可以用于签名 ConfigMap。 这一用法发生在集群启动过程的早期，在客户端信任 API 服务器之前。 被签名的 ConfigMap 可以被共享令牌完成身份认证。

通过在控制器管理器上启用 bootstrapsigner 控制器可以启用 ConfigMap 签名特性。

--controllers=*,bootstrapsigner

被签名的 ConfigMap 是 kube-public 名字空间中的 cluster-info。 典型的工作流中，客户端在未经认证和忽略 TLS 报错的状态下读取这个 ConfigMap。 通过检查 ConfigMap 中嵌入的签名校验 ConfigMap 的载荷。

ConfigMap 会是这个样子的：

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-info
  namespace: kube-public
data:
  jws-kubeconfig-07401b: eyJhbGciOiJIUzI1NiIsImtpZCI6IjA3NDAxYiJ9..tYEfbo6zDNo40MQE07aZcQX2m3EB2rO3NuXtxVMYm9U
  kubeconfig: |
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: <非常长的证书数据>
        server: https://10.138.0.2:6443
      name: ""
    contexts: []
    current-context: ""
    kind: Config
    preferences: {}
    users: []    

ConfigMap 的 kubeconfig 成员是一个填好了集群信息的配置文件。 这里主要交换的信息是 certificate-authority-data。在将来可能会有扩展。

签名是一个使用 “detached” 模式生成的 JWS 签名。 为了检验签名，用户应该按照 JWS 规则（base64 编码且丢掉结尾的 =）对 kubeconfig 的载荷进行编码。完成编码的载荷会被插入到两个句点中间，形成完整的 JWS。你可以使用完整的令牌（比如 07401b.f395accd246ae52d）作为共享密钥， 通过 HS256 方式 (HMAC-SHA256) 对 JWS 进行校验。 用户 必须 确保使用了 HS256。

警告：

任何拥有了启动引导令牌的主体都可以为该令牌生成一个合法的签名。 当使用 ConfigMap 签名时，非常不建议针对很多客户使用相同的令牌，因为某个被攻击的 客户可能对另一个一来签名来开启 TLS 信任的客户发起中间人攻击。

参考 kubeadm 实现细节 了解更多信息。

4.3 - 证书签名请求

证书 API 支持 X.509 的自动化配置， 它为 Kubernetes API 的客户端提供一个编程接口， 用于从证书颁发机构（CA）请求并获取 X.509 证书。

CertificateSigningRequest（CSR）资源用来向指定的签名者申请证书签名， 在最终签名之前，申请可能被批准，也可能被拒绝。

请求签名流程

CertificateSigningRequest 资源类型允许客户使用它申请发放 X.509 证书。 CertificateSigningRequest 对象 在 spec.request 中包含一个 PEM 编码的 PKCS#10 签名请求。 CertificateSigningRequest 使用 spec.signerName 字段标示 签名者（请求的接收方）。 注意，spec.signerName 在 certificates.k8s.io/v1 之后的 API 版本是必填项。

创建完成的 CertificateSigningRequest，要先通过批准，然后才能签名。 根据所选的签名者，CertificateSigningRequest 可能会被 控制器自动批准。 否则，就必须人工批准， 人工批准可以使用 REST API（或 go 客户端），也可以执行 kubectl certificate approve 命令。 同样，CertificateSigningRequest 也可能被驳回， 这就相当于通知了指定的签名者，这个证书不能签名。

对于已批准的证书，下一步是签名。 对应的签名控制器首先验证签名条件是否满足，然后才创建证书。 签名控制器然后更新 CertificateSigningRequest， 将新证书保存到现有 CertificateSigningRequest 对象的 status.certificate 字段中。 此时，字段 status.certificate 要么为空，要么包含一个用 PEM 编码的 X.509 证书。 直到签名完成前，CertificateSigningRequest 的字段 status.certificate 都为空。

一旦 status.certificate 字段完成填充，请求既算完成， 客户端现在可以从 CertificateSigningRequest 资源中获取已签名的证书的 PEM 数据。 当然如果不满足签名条件，签名者可以拒签。

为了减少集群中遗留的过时的 CertificateSigningRequest 资源的数量， 一个垃圾收集控制器将会周期性地运行。 此垃圾收集器会清除在一段时间内没有改变过状态的 CertificateSigningRequests：

• 已批准的请求：1小时后自动删除
• 已拒绝的请求：1小时后自动删除
• 挂起的请求：1小时后自动删除

签名者

也可以指定自定义 signerName。 所有签名者都应该提供自己工作方式的信息， 以便客户端可以预期到他们的 CSR 将发生什么。 此类信息包括：

1. 信任分发：信任（CA 证书包）是如何分发的。
2. 许可的主体：当一个受限制的主体（subject）发送请求时，相应的限制和应对手段。
3. 许可的 x509 扩展：包括 IP subjectAltNames、DNS subjectAltNames、 Email subjectAltNames、URI subjectAltNames 等，请求一个受限制的扩展项时的应对手段。
4. 许可的密钥用途/扩展的密钥用途：当用途和签名者在 CSR 中指定的用途不同时， 相应的限制和应对手段。
5. 过期时间/证书有效期：过期时间由签名者确定、由管理员配置，还是由 CSR 对象指定等， 以及过期时间与签名者在 CSR 中指定过期时间不同时的应对手段。
6. 允许/不允许 CA 位：当 CSR 包含一个签名者并不允许的 CA 证书的请求时，相应的应对手段。

一般来说，当 CSR 被批准通过，且证书被签名后，status.certificate 字段 将包含一个 PEM 编码的 X.509 证书。 有些签名者在 status.certificate 字段中存储多个证书。 在这种情况下，签名者的说明文档应当指明附加证书的含义。 例如，这是要在 TLS 握手时提供的证书和中继证书。

PKCS#10 签名请求格式不允许设置证书的过期时间或者生命期。因此，证书的过期 时间或者生命期必须通过类似 CSR 对象的注解字段这种形式来设置。 尽管让签名者使用过期日期从理论上来讲也是可行的，目前还不存在哪个实现这样做了。 （内置的签名者都是用相同的 ClusterSigningDuration 配置选项，而该选项 中将生命期的默认值设为 1 年，且可通过 kube-controller-manager 的命令行选项 --cluster-signing-duration 来更改。）

Kubernetes 签名者

Kubernetes提供了内置的签名者，每个签名者都有一个众所周知的 signerName:

1. kubernetes.io/kube-apiserver-client：签名的证书将被 API 服务器视为客户证书。 kube-controller-manager 不会自动批准它。
   1. 信任分发：签名的证书将被 API 服务器视为客户端证书。CA 证书包不通过任何其他方式分发。
   2. 许可的主体：没有主体限制，但审核人和签名者可以选择不批准或不签署。 某些主体，比如集群管理员级别的用户或组因部署和安装方式不同而不同， 所以批准和签署之前需要进行额外仔细审查。 用来限制 system:masters 的 CertificateSubjectRestriction 准入插件默认处于启用状态， 但它通常不是集群中唯一的集群管理员主体。
   3. 许可的 x509 扩展：允许 subjectAltName 和 key usage 扩展，弃用其他扩展。
   4. 许可的密钥用途：必须包含 ["client auth"]，但不能包含 ["digital signature", "key encipherment", "client auth"] 之外的键。
   5. 过期时间/证书有效期：通过 kube-controller-manager 中 --cluster-signing-duration 标志来设置，由其中的签名者实施。
   6. 允许/不允许 CA 位：不允许。

2. kubernetes.io/kube-apiserver-client-kubelet: 签名的证书将被 kube-apiserver 视为客户证书。 kube-controller-manager 可以自动批准它。

   1. 信任分发：签名的证书将被 API 服务器视为客户端证书。CA 证书包不通过任何其他方式分发。
   2. 许可的主体：组织名必须是 ["system:nodes"]，用户名以 "system:node:" 开头
   3. 许可的 x509 扩展：允许 key usage 扩展，禁用 subjectAltName 扩展，并删除其他扩展。
   4. 许可的密钥用途：必须是 ["key encipherment", "digital signature", "client auth"]
   5. 过期时间/证书有效期：通过 kube-controller-manager 中签名者的实现所对应的标志 --cluster-signing-duration 来设置。
   6. 允许/不允许 CA 位：不允许。

3. kubernetes.io/kubelet-serving: 签名服务证书，该服务证书被 API 服务器视为有效的 kubelet 服务证书， 但没有其他保证。kube-controller-manager 不会自动批准它。
   1. 信任分发：签名的证书必须被 kube-apiserver 认可，可有效的中止 kubelet 连接。CA 证书包不通过任何其他方式分发。
   2. 许可的主体：组织名必须是 ["system:nodes"]，用户名以 "system:node:" 开头
   3. 许可的 x509 扩展：允许 key usage、DNSName/IPAddress subjectAltName 等扩展， 禁止 EmailAddress、URI subjectAltName 等扩展，并丢弃其他扩展。 至少有一个 DNS 或 IP 的 SubjectAltName 存在。
   4. 许可的密钥用途：必须是 ["key encipherment", "digital signature", "client auth"]
   5. 过期日期/证书生命期：通过 kube-controller-manager 中签名者的实现所对应的标志 --cluster-signing-duration 来设置。
   6. 允许/不允许 CA 位：不允许。

4. kubernetes.io/legacy-unknown: 不保证信任。Kubernetes 的一些第三方发行版可能会使用它签署的客户端证书。 稳定版的 CertificateSigningRequest API（certificates.k8s.io/v1 以及之后的版本）不允许将 signerName 设置为 kubernetes.io/legacy-unknown。 kube-controller-manager 不会自动批准这类请求。
   1. 信任分发：没有。这个签名者在 Kubernetes 集群中没有标准的信任或分发。
   2. 许可的主体：全部。
   3. 许可的 x509 扩展：允许 subjectAltName 和 key usage 等扩展，并弃用其他扩展。
   4. 许可的密钥用途：全部。
   5. 过期日期/证书生命期：通过 kube-controller-manager 中签名者的实现所对应的标志 --cluster-signing-duration 来设置。
   6. 允许/不允许 CA 位 - 不允许。

说明：

注意：所有这些故障仅在 kube-controller-manager 日志中报告。

对于这些签名者，信任的分发发生在带外（out of band）。上述信任之外的任何信任都是完全巧合的。 例如，一些发行版可能会将 kubernetes.io/legacy-unknown 作为 kube-apiserver 的客户端证书， 但这个做法并不标准。 这些用途都没有以任何方式涉及到 ServiceAccount 中的 Secrets .data[ca.crt]。 此 CA 证书包只保证使用默认的服务（kubernetes.default.svc）来验证到 API 服务器的连接。

鉴权

授权创建 CertificateSigningRequest 和检索 CertificateSigningRequest:

• verbs（动词）: create、get、list、watch, group（组）：certificates.k8s.io， resources：certificatesigningrequests

例如：

access/certificate-signing-request/clusterrole-create.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: csr-creator
rules:
- apiGroups:
  - certificates.k8s.io
  resources:
  - certificatesigningrequests
  verbs:
  - create
  - get
  - list
  - watch

授权批准 CertificateSigningRequest：

• verbs（动词）: get、list、watch， group（组）：certificates.k8s.io， resources（资源）：certificatesigningrequests
• verbs（动词）: update， group（组）：certificates.k8s.io， resources（资源）：certificatesigningrequests/approval
• verbs（动词）：approve， group（组）：certificates.k8s.io， resources（资源）：signers， resourceName：<signerNameDomain>/<signerNamePath> 或 <signerNameDomain>/*

例如：

access/certificate-signing-request/clusterrole-approve.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: csr-approver
rules:
- apiGroups:
  - certificates.k8s.io
  resources:
  - certificatesigningrequests
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - certificates.k8s.io
  resources:
  - certificatesigningrequests/approval
  verbs:
  - update
- apiGroups:
  - certificates.k8s.io
  resources:
  - signers
  resourceNames:
  - example.com/my-signer-name # example.com/* can be used to authorize for all signers in the 'example.com' domain
  verbs:
  - approve

授权签名 CertificateSigningRequest：

• verbs（动词）：get、list、watch， group（组）：certificates.k8s.io， resources（资源）：certificatesigningrequests
• verbs（动词）：update， group（组）：certificates.k8s.io， resources（资源）：certificatesigningrequests/status
• verbs（动词）：sign， group（组）：certificates.k8s.io， resources（资源）：signers， resourceName：<signerNameDomain>/<signerNamePath> 或 <signerNameDomain>/*

access/certificate-signing-request/clusterrole-sign.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: csr-signer
rules:
- apiGroups:
  - certificates.k8s.io
  resources:
  - certificatesigningrequests
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - certificates.k8s.io
  resources:
  - certificatesigningrequests/status
  verbs:
  - update
- apiGroups:
  - certificates.k8s.io
  resources:
  - signers
  resourceNames:
  - example.com/my-signer-name # example.com/* can be used to authorize for all signers in the 'example.com' domain
  verbs:
  - sign

普通用户

为了让普通用户能够通过认证并调用 API，需要执行几个步骤。 首先，该用户必须拥有 Kubernetes 集群签发的证书， 然后将该证书作为 API 调用的 Certificate 头或通过 kubectl 提供。

创建私钥

下面的脚本展示了如何生成 PKI 私钥和 CSR。 设置 CSR 的 CN 和 O 属性很重要。CN 是用户名，O 是该用户归属的组。 你可以参考 RBAC 了解标准组的信息。

openssl genrsa -out myuser.key 2048
openssl req -new -key myuser.key -out myuser.csr

创建 CertificateSigningRequest

创建一个 CertificateSigningRequest，并通过 kubectl 将其提交到 Kubernetes 集群。 下面是生成 CertificateSigningRequest 的脚本。

cat <<EOF | kubectl apply -f -
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
  name: myuser
spec:
  groups:
  - system:authenticated
  request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ1ZqQ0NBVDRDQVFBd0VURVBNQTBHQTFVRUF3d0dZVzVuWld4aE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRgpBQU9DQVE4QU1JSUJDZ0tDQVFFQTByczhJTHRHdTYxakx2dHhWTTJSVlRWMDNHWlJTWWw0dWluVWo4RElaWjBOCnR2MUZtRVFSd3VoaUZsOFEzcWl0Qm0wMUFSMkNJVXBGd2ZzSjZ4MXF3ckJzVkhZbGlBNVhwRVpZM3ExcGswSDQKM3Z3aGJlK1o2MVNrVHF5SVBYUUwrTWM5T1Nsbm0xb0R2N0NtSkZNMUlMRVI3QTVGZnZKOEdFRjJ6dHBoaUlFMwpub1dtdHNZb3JuT2wzc2lHQ2ZGZzR4Zmd4eW8ybmlneFNVekl1bXNnVm9PM2ttT0x1RVF6cXpkakJ3TFJXbWlECklmMXBMWnoyalVnald4UkhCM1gyWnVVV1d1T09PZnpXM01LaE8ybHEvZi9DdS8wYk83c0x0MCt3U2ZMSU91TFcKcW90blZtRmxMMytqTy82WDNDKzBERHk5aUtwbXJjVDBnWGZLemE1dHJRSURBUUFCb0FBd0RRWUpLb1pJaHZjTgpBUUVMQlFBRGdnRUJBR05WdmVIOGR4ZzNvK21VeVRkbmFjVmQ1N24zSkExdnZEU1JWREkyQTZ1eXN3ZFp1L1BVCkkwZXpZWFV0RVNnSk1IRmQycVVNMjNuNVJsSXJ3R0xuUXFISUh5VStWWHhsdnZsRnpNOVpEWllSTmU3QlJvYXgKQVlEdUI5STZXT3FYbkFvczFqRmxNUG5NbFpqdU5kSGxpT1BjTU1oNndLaTZzZFhpVStHYTJ2RUVLY01jSVUyRgpvU2djUWdMYTk0aEpacGk3ZnNMdm1OQUxoT045UHdNMGM1dVJVejV4T0dGMUtCbWRSeEgvbUNOS2JKYjFRQm1HCkkwYitEUEdaTktXTU0xMzhIQXdoV0tkNjVoVHdYOWl4V3ZHMkh4TG1WQzg0L1BHT0tWQW9FNkpsYWFHdTlQVmkKdjlOSjVaZlZrcXdCd0hKbzZXdk9xVlA3SVFjZmg3d0drWm89Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
  signerName: kubernetes.io/kube-apiserver-client
  usages:
  - client auth
EOF

需要注意的几点:

• usage 字段必须是 'client auth'
• request 字段是 CSR 文件内容的 base64 编码值。 要得到该值，可以执行命令 cat myuser.csr | base64 | tr -d "\n"。

批准证书签名请求

使用 kubectl 创建 CSR 并批准。

获取 CSR 列表：

kubectl get csr

批准 CSR：

kubectl certificate approve myuser

取得证书

从 CSR 取得证书：

kubectl get csr/myuser -o yaml

证书的内容使用 base64 编码，存放在字段 status.certificate。

从 CertificateSigningRequest 导出颁发的证书。

kubectl get csr myuser -o jsonpath='{.status.certificate}'| base64 -d > myuser.crt

创建角色和角色绑定

创建了证书之后，为了让这个用户能访问 Kubernetes 集群资源，现在就要创建 Role 和 RoleBinding 了。

下面是为这个新用户创建 Role 的示例脚本：

kubectl create role developer --verb=create --verb=get --verb=list --verb=update --verb=delete --resource=pods

下面是为这个新用户创建 RoleBinding 的示例命令：

kubectl create rolebinding developer-binding-myuser --role=developer --user=myuser

添加到 kubeconfig

最后一步是将这个用户添加到 kubeconfig 文件。 我们假设私钥和证书文件存放在 “/home/vagrant/work/” 目录中。

首先，我们需要添加新的凭据：

kubectl config set-credentials myuser --client-key=myuser.key --client-certificate=myuser.crt --embed-certs=true

然后，你需要添加上下文：

kubectl config set-context myuser --cluster=kubernetes --user=myuser

来测试一下，把上下文切换为 myuser：

kubectl config use-context myuser

批准和驳回

控制平面的自动化批准

kube-controller-manager 内建了一个证书批准者，其 signerName 为 kubernetes.io/kube-apiserver-client-kubelet， 该批准者将 CSR 上用于节点凭据的各种权限委托给权威认证机构。 kube-controller-manager 将 SubjectAccessReview 资源发送（POST）到 API 服务器， 以便检验批准证书的授权。

使用 kubectl 批准或驳回

Kubernetes 管理员（拥有足够的权限）可以手工批准（或驳回）CertificateSigningRequests， 此操作使用 kubectl certificate approve 和 kubectl certificate deny 命令实现。

使用 kubectl 批准一个 CSR：

kubectl certificate approve <certificate-signing-request-name>

同样地，驳回一个 CSR：

kubectl certificate deny <certificate-signing-request-name>

使用 Kubernetes API 批准或驳回

REST API 的用户可以通过向待批准的 CSR 的 approval 子资源提交更新请求来批准 CSR。 例如，你可以编写一个 operator 来监视特定类型的 CSR，然后发送一个更新来批准它。

当你发出批准或驳回的指令时，根据你期望的状态来选择设置 Approved 或 Denied。

批准（Approved） 的 CSR：

apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
...
status:
  conditions:
  - lastUpdateTime: "2020-02-08T11:37:35Z"
    lastTransitionTime: "2020-02-08T11:37:35Z"
    message: Approved by my custom approver controller
    reason: ApprovedByMyPolicy # You can set this to any string
    type: Approved

驳回（Denied）的 CRS：

apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
...
status:
  conditions:
  - lastUpdateTime: "2020-02-08T11:37:35Z"
    lastTransitionTime: "2020-02-08T11:37:35Z"
    message: Denied by my custom approver controller
    reason: DeniedByMyPolicy # You can set this to any string
    type: Denied

status.conditions.reason 字段通常设置为一个首字母大写的对机器友好的原因码; 这是一个命名约定，但你也可以随你的个人喜好设置。 如果你想添加一个供人类使用的注释，那就用 status.conditions.message 字段。

签名

控制平面签名者

Kubernetes 控制平面实现了每一个 Kubernetes 签名者， 每个签名者的实现都是 kube-controller-manager 的一部分。

说明： 在Kubernetes v1.18 之前， kube-controller-manager 签名所有标记为 approved 的 CSR。

基于 API 的签名者

REST API 的用户可以通过向待签名的 CSR 的 status 子资源提交更新请求来对 CSR 进行签名。

作为这个请求的一部分， status.certificate 字段应设置为已签名的证书。 此字段可包含一个或多个 PEM 编码的证书。

所有的 PEM 块必须具备 "CERTIFICATE" 标签，且不包含文件头，且编码的数据必须是 RFC5280 第 4 节 中描述的 BER 编码的 ASN.1 证书结构。

-----BEGIN CERTIFICATE-----
MIIDgjCCAmqgAwIBAgIUC1N1EJ4Qnsd322BhDPRwmg3b/oAwDQYJKoZIhvcNAQEL
BQAwXDELMAkGA1UEBhMCeHgxCjAIBgNVBAgMAXgxCjAIBgNVBAcMAXgxCjAIBgNV
BAoMAXgxCjAIBgNVBAsMAXgxCzAJBgNVBAMMAmNhMRAwDgYJKoZIhvcNAQkBFgF4
MB4XDTIwMDcwNjIyMDcwMFoXDTI1MDcwNTIyMDcwMFowNzEVMBMGA1UEChMMc3lz
dGVtOm5vZGVzMR4wHAYDVQQDExVzeXN0ZW06bm9kZToxMjcuMC4wLjEwggEiMA0G
CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDne5X2eQ1JcLZkKvhzCR4Hxl9+ZmU3
+e1zfOywLdoQxrPi+o4hVsUH3q0y52BMa7u1yehHDRSaq9u62cmi5ekgXhXHzGmm
kmW5n0itRECv3SFsSm2DSghRKf0mm6iTYHWDHzUXKdm9lPPWoSOxoR5oqOsm3JEh
Q7Et13wrvTJqBMJo1GTwQuF+HYOku0NF/DLqbZIcpI08yQKyrBgYz2uO51/oNp8a
sTCsV4OUfyHhx2BBLUo4g4SptHFySTBwlpRWBnSjZPOhmN74JcpTLB4J5f4iEeA7
2QytZfADckG4wVkhH3C2EJUmRtFIBVirwDn39GXkSGlnvnMgF3uLZ6zNAgMBAAGj
YTBfMA4GA1UdDwEB/wQEAwIFoDATBgNVHSUEDDAKBggrBgEFBQcDAjAMBgNVHRMB
Af8EAjAAMB0GA1UdDgQWBBTREl2hW54lkQBDeVCcd2f2VSlB1DALBgNVHREEBDAC
ggAwDQYJKoZIhvcNAQELBQADggEBABpZjuIKTq8pCaX8dMEGPWtAykgLsTcD2jYr
L0/TCrqmuaaliUa42jQTt2OVsVP/L8ofFunj/KjpQU0bvKJPLMRKtmxbhXuQCQi1
qCRkp8o93mHvEz3mTUN+D1cfQ2fpsBENLnpS0F4G/JyY2Vrh19/X8+mImMEK5eOy
o0BMby7byUj98WmcUvNCiXbC6F45QTmkwEhMqWns0JZQY+/XeDhEcg+lJvz9Eyo2
aGgPsye1o3DpyXnyfJWAWMhOz7cikS5X2adesbgI86PhEHBXPIJ1v13ZdfCExmdd
M1fLPhLyR54fGaY+7/X8P9AZzPefAkwizeXwe9ii6/a08vWoiE4=
-----END CERTIFICATE-----

非 PEM 内容可能会出现在证书 PEM 块前后的位置，且未经验证， 以允许使用 RFC7468 第5.2节 中描述的解释性文本。

当使用 JSON 或 YAML 格式时，此字段是 base-64 编码。 包含上述示例证书的 CertificateSigningRequest 如下所示：

apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
...
status:
  certificate: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JS..."

接下来

• 参阅 管理集群中的 TLS 认证
• 查看 kube-controller-manager 中签名者部分的源代码
• 查看 kube-controller-manager 中批准者部分的源代码
• 有关 X.509 本身的详细信息，请参阅 RFC 5280 第3.1节
• 有关 PKCS#10 证书签名请求语法的信息，请参阅 RFC 2986

4.4 - 使用准入控制器

此页面概述了准入控制器。

什么是准入控制插件？

准入控制器是一段代码，它会在请求通过认证和授权之后、对象被持久化之前拦截到达 API 服务器的请求。控制器由下面的列表组成， 并编译进 kube-apiserver 二进制文件，并且只能由集群管理员配置。 在该列表中，有两个特殊的控制器：MutatingAdmissionWebhook 和 ValidatingAdmissionWebhook。 它们根据 API 中的配置，分别执行变更和验证 准入控制 webhook。

准入控制器可以执行 “验证（Validating）” 和/或 “变更（Mutating）” 操作。 变更（mutating）控制器可以修改被其接受的对象；验证（validating）控制器则不行。

准入控制过程分为两个阶段。第一阶段，运行变更准入控制器。第二阶段，运行验证准入控制器。 再次提醒，某些控制器既是变更准入控制器又是验证准入控制器。

如果任何一个阶段的任何控制器拒绝了该请求，则整个请求将立即被拒绝，并向终端用户返回一个错误。

最后，除了对对象进行变更外，准入控制器还可以有其它作用：将相关资源作为请求处理的一部分进行变更。 增加使用配额就是一个典型的示例，说明了这样做的必要性。 此类用法都需要相应的回收或回调过程，因为任一准入控制器都无法确定某个请求能否通过所有其它准入控制器。

为什么需要准入控制器？

Kubernetes 的许多高级功能都要求启用一个准入控制器，以便正确地支持该特性。 因此，没有正确配置准入控制器的 Kubernetes API 服务器是不完整的，它无法支持你期望的所有特性。

如何启用一个准入控制器？

Kubernetes API 服务器的 enable-admission-plugins 标志接受一个用于在集群修改对象之前 调用的（以逗号分隔的）准入控制插件顺序列表。

例如，下面的命令就启用了 NamespaceLifecycle 和 LimitRanger 准入控制插件：

kube-apiserver --enable-admission-plugins=NamespaceLifecycle,LimitRanger ...

说明：

根据你 Kubernetes 集群的部署方式以及 API 服务器的启动方式的不同，你可能需要以不同的方式应用设置。 例如，如果将 API 服务器部署为 systemd 服务，你可能需要修改 systemd 单元文件； 如果以自托管方式部署 Kubernetes，你可能需要修改 API 服务器的清单文件。

怎么关闭准入控制器？

Kubernetes API 服务器的 disable-admission-plugins 标志，会将传入的（以逗号分隔的） 准入控制插件列表禁用，即使是默认启用的插件也会被禁用。

kube-apiserver --disable-admission-plugins=PodNodeSelector,AlwaysDeny ...

哪些插件是默认启用的？

下面的命令可以查看哪些插件是默认启用的：

kube-apiserver -h | grep enable-admission-plugins

在目前版本中，它们是：

CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, LimitRanger, MutatingAdmissionWebhook, NamespaceLifecycle, PersistentVolumeClaimResize, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionWebhook

每个准入控制器的作用是什么？

AlwaysAdmit

该准入控制器会允许所有的 pod 接入集群。已废弃，因为它的行为根本就和没有准入控制器一样。

AlwaysDeny

拒绝所有的请求。由于它没有实际意义，已废弃。

AlwaysPullImages

该准入控制器会修改每一个新创建的 Pod 的镜像拉取策略为 Always 。 这在多租户集群中是有用的，这样用户就可以放心，他们的私有镜像只能被那些有凭证的人使用。 如果没有这个准入控制器，一旦镜像被拉取到节点上，任何用户的 Pod 都可以通过已了解到的镜像 的名称（假设 Pod 被调度到正确的节点上）来使用它，而不需要对镜像进行任何授权检查。 当启用这个准入控制器时，总是在启动容器之前拉取镜像，这意味着需要有效的凭证。

CertificateApproval

此准入控制器获取“审批” CertificateSigningRequest 资源的请求并执行额外的授权检查， 以确保审批请求的用户有权限审批 spec.signerName 请求 CertificateSigningRequest 资源的证书请求。

有关对证书签名请求资源执行不同操作所需权限的详细信息， 请参阅证书签名请求

CertificateSigning

此准入控制器获取 CertificateSigningRequest 资源的 status.certificate 字段更新请求并执行额外的授权检查， 以确保签发证书的用户有权限为 spec.signerName 请求 CertificateSigningRequest 资源的证书请求签发证书。

有关对证书签名请求资源执行不同操作所需权限的详细信息， 请参阅证书签名请求

CertificateSubjectRestrictions

此准入控制器获取具有 kubernetes.io/kube-apiserver-client 的 spec.signerName 的 CertificateSigningRequest 资源创建请求， 它拒绝任何包含了 system:masters 一个“组”（或者“组织”）的请求。

DefaultIngressClass

该准入控制器监测没有请求任何特定 Ingress 类的 Ingress 对象的创建，并自动向其添加默认 Ingress 类。 这样，没有任何特殊 Ingress 类需求的用户根本不需要关心它们，它们将获得默认 Ingress 类。

当未配置默认 Ingress 类时，此准入控制器不执行任何操作。如果将多个 Ingress 类标记为默认 Ingress 类， 它将拒绝任何创建 Ingress 的操作，并显示错误。 要修复此错误，管理员必须重新检查其 IngressClass 对象，并仅将其中一个标记为默认（通过注解 "ingressclass.kubernetes.io/is-default-class"）。 此准入控制器会忽略所有 Ingress 更新操作，仅响应创建操作。

关于 Ingress 类以及如何将 Ingress 类标记为默认的更多信息，请参见 ingress。

DefaultStorageClass

该准入控制器监测没有请求任何特定存储类的 PersistentVolumeClaim 对象的创建， 并自动向其添加默认存储类。 这样，没有任何特殊存储类需求的用户根本不需要关心它们，它们将获得默认存储类。

当未配置默认存储类时，此准入控制器不执行任何操作。如果将多个存储类标记为默认存储类， 它将拒绝任何创建 PersistentVolumeClaim 的操作，并显示错误。 要修复此错误，管理员必须重新访问其 StorageClass 对象，并仅将其中一个标记为默认。 此准入控制器会忽略所有 PersistentVolumeClaim 更新操作，仅响应创建操作。

关于持久化卷和存储类，以及如何将存储类标记为默认，请参见 持久化卷。

DefaultTolerationSeconds

该准入控制器基于 k8s-apiserver 输入参数 default-not-ready-toleration-seconds 和 default-unreachable-toleration-seconds 为 Pod 设置默认的容忍度，以容忍 notready:NoExecute 和 unreachable:NoExecute 污点。 （如果 Pod 尚未容忍 node.kubernetes.io/not-ready：NoExecute 和 node.kubernetes.io/unreachable：NoExecute 污点的话） default-not-ready-toleration-seconds 和 default-unreachable-toleration-seconds 的默认值是 5 分钟。

DenyEscalatingExec

该准入控制器将拒绝在由于拥有升级特权，而具备访问宿主机能力的 Pod 中执行 exec 和 attach 命令。这包括在特权模式运行的 Pod，可以访问主机 IPC 名字空间的 Pod， 和访问主机 PID 名字空间的 Pod 。

DenyExecOnPrivileged 准入插件已被废弃。

建议使用基于策略的准入插件（例如 PodSecurityPolicy 和自定义准入插件）， 该插件可以针对特定用户或名字空间，还可以防止创建权限过高的 Pod。

DenyExecOnPrivileged

如果一个 pod 拥有一个特权容器，该准入控制器将拦截所有在该 pod 中执行 exec 命令的请求。

此功能已合并至 DenyEscalatingExec。 而 DenyExecOnPrivileged 准入插件已被废弃。

建议使用基于策略的准入插件（例如 PodSecurityPolicy 和自定义准入插件）， 该插件可以针对特定用户或名字空间，还可以防止创建权限过高的 Pod。

DenyServiceExternalIPs

该准入控制器拒绝 Service 字段 externalIPs 的所有新规使用。 此功能非常强大（允许网络流量拦截）， 并且无法很好地受策略控制。 启用后，群集用户将无法创建使用 externalIPs 的新服务，也无法在现有 Service 对象上向 externalIPs 添加新值。 externalIPs 的现有使用不受影响，用户可以从现有 Service 对象上的 externalIPs 中删除值。

大多数用户根本不需要此功能，集群管理员应考虑将其禁用。 确实需要使用此功能的集群应考虑使用一些自定义策略来管理其的使用。

EventRateLimit

该准入控制器缓解了事件请求淹没 API 服务器的问题。集群管理员可以通过以下方式指定事件速率限制：

• 启用 EventRateLimit 准入控制器；
• 从文件中引用 EventRateLimit 配置文件，并提供给 API 服务器命令的 --admission-control-config-file 标志：

• apiserver.config.k8s.io/v1
• apiserver.k8s.io/v1alpha1

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: EventRateLimit
  path: eventconfig.yaml
...

# Deprecated in v1.17 in favor of apiserver.config.k8s.io/v1
apiVersion: apiserver.k8s.io/v1alpha1
kind: AdmissionConfiguration
plugins:
- name: EventRateLimit
  path: eventconfig.yaml
...

可以在配置中指定四种类型的限制：

• Server: API 服务器收到的所有事件请求共享一个桶。
• Namespace: 每个名字空间都有一个专用的桶。
• User: 给每个用户都分配一个桶。
• SourceAndObject: 根据事件的源和涉及对象的每种组合分配桶。

下面是一个配置示例 eventconfig.yaml：

apiVersion: eventratelimit.admission.k8s.io/v1alpha1
kind: Configuration
limits:
- type: Namespace
  qps: 50
  burst: 100
  cacheSize: 2000
- type: User
  qps: 10
  burst: 50

详情请参见 事件速率限制提案。

ExtendedResourceToleration

该插件有助于创建可扩展资源的专用节点。 如果运营商想创建可扩展资源的专用节点（如 GPU、FPGA 等）， 那他们应该以扩展资源名称作为键名， 为节点设置污点。 如果启用了该准入控制器，会将此类污点的容忍自动添加到请求扩展资源的 Pod 中， 用户不必再手动添加这些容忍。

ImagePolicyWebhook

ImagePolicyWebhook 准入控制器允许使用一个后端的 webhook 做出准入决策。

配置文件格式

ImagePolicyWebhook 使用配置文件来为后端行为设置配置选项。该文件可以是 JSON 或 YAML， 并具有以下格式:

imagePolicy:
  kubeConfigFile: /path/to/kubeconfig/for/backend
  # 以秒计的时长，控制批准请求的缓存时间
  allowTTL: 50
  # 以秒计的时长，控制批准请求的缓存时间
  denyTTL: 50
  # 以毫秒计的时长，控制重试间隔
  retryBackoff: 500
  # 确定 Webhook 后端失效时的行为
  defaultAllow: true

从文件中引用 ImagePolicyWebhook 的配置文件，并将其提供给 API 服务器命令标志 --admission-control-config-file：

• apiserver.config.k8s.io/v1
• apiserver.k8s.io/v1alpha1

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: ImagePolicyWebhook
  path: imagepolicyconfig.yaml
...

# v1.17 中已废弃以鼓励使用 apiserver.config.k8s.io/v1
apiVersion: apiserver.k8s.io/v1alpha1
kind: AdmissionConfiguration
plugins:
- name: ImagePolicyWebhook
  path: imagepolicyconfig.yaml
...

或者，你也可以直接将配置嵌入到文件中：

• apiserver.config.k8s.io/v1
• apiserver.k8s.io/v1alpha1

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: ImagePolicyWebhook
  configuration:
    imagePolicy:
      kubeConfigFile: <kubeconfig 文件路径>
      allowTTL: 50
      denyTTL: 50
      retryBackoff: 500
      defaultAllow: true

# v1.17 中已废弃以鼓励使用 apiserver.config.k8s.io/v1
apiVersion: apiserver.k8s.io/v1alpha1
kind: AdmissionConfiguration
plugins:
- name: ImagePolicyWebhook
  configuration:
    imagePolicy:
      kubeConfigFile: <kubeconfig 文件路径>
      allowTTL: 50
      denyTTL: 50
      retryBackoff: 500
      defaultAllow: true

ImagePolicyWebhook 的配置文件必须引用 kubeconfig 格式的文件；该文件设置了到后端的连接参数。 要求后端使用 TLS 进行通信。

kubeconfig 文件的 cluster 字段需要指向远端服务，user 字段需要包含已返回的授权者。

# clusters 指的是远程服务。
clusters:
- name: name-of-remote-imagepolicy-service
  cluster:
    certificate-authority: /path/to/ca.pem    # CA 用于验证远程服务
    server: https://images.example.com/policy # 要查询的远程服务的 URL。必须是 'https' 。

# users 指的是 API 服务器的 Webhook 配置。
users:
- name: name-of-api-server
  user:
    client-certificate: /path/to/cert.pem # webhook 准入控制器使用的证书
    client-key: /path/to/key.pem          # 证书匹配的密钥

关于 HTTP 配置的更多信息，请参阅 kubeconfig 文档。

请求载荷

当面对一个准入决策时，API 服务器发送一个描述操作的 JSON 序列化的 imagepolicy.k8s.io/v1alpha1 ImageReview 对象。 该对象包含描述被审核容器的字段，以及所有匹配 *.image-policy.k8s.io/* 的 Pod 注解。

注意，Webhook API 对象与其他 Kubernetes API 对象一样受制于相同的版本控制兼容性规则。 实现者应该知道对 alpha 对象的更宽松的兼容性，并检查请求的 "apiVersion" 字段， 以确保正确的反序列化。 此外，API 服务器必须启用 imagepolicy.k8s.io/v1alpha1 API 扩展组 （--runtime-config=imagepolicy.k8s.io/v1alpha1=true）。

请求载荷示例：

{
  "apiVersion":"imagepolicy.k8s.io/v1alpha1",
  "kind":"ImageReview",
  "spec":{
    "containers":[
      {
        "image":"myrepo/myimage:v1"
      },
      {
        "image":"myrepo/myimage@sha256:beb6bd6a68f114c1dc2ea4b28db81bdf91de202a9014972bec5e4d9171d90ed"
      }
    ],
    "annotations":{
      "mycluster.image-policy.k8s.io/ticket-1234": "break-glass"
    },
    "namespace":"mynamespace"
  }
}

远程服务将填充请求的 ImageReviewStatus 字段，并返回允许或不允许访问的响应。 响应体的 "spec" 字段会被忽略，并且可以省略。一个允许访问应答会返回：

{
  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
  "kind": "ImageReview",
  "status": {
    "allowed": true
  }
}

若不允许访问，服务将返回：

{
  "apiVersion": "imagepolicy.k8s.io/v1alpha1",
  "kind": "ImageReview",
  "status": {
    "allowed": false,
    "reason": "image currently blacklisted"
  }
}

更多的文档，请参阅 imagepolicy.v1alpha1 API 对象和 plugin/pkg/admission/imagepolicy/admission.go。

使用注解进行扩展

一个 Pod 中匹配 *.image-policy.k8s.io/* 的注解都会被发送给 Webhook。 这样做使得了解后端镜像策略的用户可以向它发送额外的信息，并为不同的后端实现 接收不同的信息。

你可以在这里输入的信息有：

• 在紧急情况下，请求 "break glass" 覆盖一个策略。
• 从一个记录了 break-glass 的请求的 ticket 系统得到的一个 ticket 号码。
• 向策略服务器提供一个提示，用于提供镜像的 imageID，以方便它进行查找。

在任何情况下，注解都是由用户提供的，并不会被 Kubernetes 以任何方式进行验证。 在将来，如果一个注解确定将被广泛使用，它可能会被提升为 ImageReviewSpec 的一个命名字段。

LimitPodHardAntiAffinityTopology

该准入控制器拒绝（定义了 AntiAffinity 拓扑键的）任何 Pod （requiredDuringSchedulingRequiredDuringExecution 中的 kubernetes.io/hostname 除外）。

LimitRanger

该准入控制器会观察传入的请求，并确保它不会违反 Namespace 中 LimitRange 对象枚举的任何约束。 如果你在 Kubernetes 部署中使用了 LimitRange 对象，则必须使用此准入控制器来 执行这些约束。 LimitRanger 还可以用于将默认资源请求应用到没有指定任何内容的 Pod； 当前，默认的 LimitRanger 对 default 名字空间中的所有 Pod 都应用了 0.1 CPU 的需求。

请查看 limitRange 设计文档 和 LimitRange 例子 以了解更多细节。

MutatingAdmissionWebhook

该准入控制器调用任何与请求匹配的变更 Webhook。匹配的 Webhook 将被串行调用。 每一个 Webhook 都可以根据需要修改对象。

MutatingAdmissionWebhook，顾名思义，仅在变更阶段运行。

如果由此准入控制器调用的 Webhook 有副作用（如降低配额）， 则它 必须 具有协调系统，因为不能保证后续的 Webhook 和验证准入控制器都会允许完成请求。

如果你禁用了 MutatingAdmissionWebhook，那么还必须使用 --runtime-config 标志禁止 admissionregistration.k8s.io/v1 组/版本中的 MutatingWebhookConfiguration 对象（版本 >=1.9 时，这两个对象都是默认启用的）。

谨慎编写和安装变更 webhook

• 当用户尝试创建的对象与返回的对象不同时，用户可能会感到困惑。
• 当它们回读的对象与尝试创建的对象不同，内建的控制环可能会出问题。
  • 与覆盖原始请求中设置的字段相比，使用原始请求未设置的字段会引起问题的可能性较小。 应尽量避免前面那种方式。
• 内建资源和第三方资源的控制回路未来可能会受到破坏性的更改，使现在运行良好的 Webhook 无法再正常运行。即使完成了 Webhook API 安装，也不代表会为该 webhook 提供无限期的支持。

NamespaceAutoProvision

该准入控制器会检查名字空间资源上的所有传入请求，并检查所引用的名字空间是否确实存在。 如果找不到，它将创建一个名字空间。 此准入控制器对于不想要求名字空间必须先创建后使用的集群部署中很有用。

NamespaceExists

该准入控制器检查除 Namespace 以外的名字空间作用域资源上的所有请求。 如果请求引用的名字空间不存在，则拒绝该请求。

NamespaceLifecycle

该准入控制器禁止在一个正在被终止的 Namespace 中创建新对象，并确保 使用不存在的 Namespace 的请求被拒绝。 该准入控制器还会禁止删除三个系统保留的名字空间，即 default、 kube-system 和 kube-public。

删除 Namespace 会触发删除该名字空间中所有对象（Pod、Service 等）的一系列操作。 为了确保这个过程的完整性，我们强烈建议启用这个准入控制器。

NodeRestriction

该准入控制器限制了 kubelet 可以修改的 Node 和 Pod 对象。 为了受到这个准入控制器的限制，kubelet 必须使用在 system:nodes 组中的凭证， 并使用 system:node:<nodeName> 形式的用户名。 这样，kubelet 只可修改自己的 Node API 对象，只能修改绑定到节点本身的 Pod 对象。

在 Kubernetes 1.11+ 的版本中，不允许 kubelet 从 Node API 对象中更新或删除污点。

在 Kubernetes 1.13+ 的版本中，NodeRestriction 准入插件可防止 kubelet 删除 Node API 对象，并对 kubernetes.io/ 或 k8s.io/ 前缀标签的 kubelet 强制进行如下修改：

• 防止 kubelet 添加/删除/更新带有 node-restriction.kubernetes.io/ 前缀的标签。 保留此前缀的标签，供管理员用来标记 Node 对象以隔离工作负载，并且不允许 kubelet 修改带有该前缀的标签。
• 允许 kubelet 添加/删除/更新这些和这些前缀的标签：
  • kubernetes.io/hostname
  • kubernetes.io/arch
  • kubernetes.io/os
  • beta.kubernetes.io/instance-type
  • node.kubernetes.io/instance-type
  • failure-domain.beta.kubernetes.io/region （已弃用）
  • failure-domain.beta.kubernetes.io/zone (已弃用）
  • topology.kubernetes.io/region
  • topology.kubernetes.io/zone
  • kubelet.kubernetes.io/-prefixed labels
  • node.kubernetes.io/-prefixed labels

kubelet 保留 kubernetes.io 或 k8s.io 前缀的所有标签，并且将来可能会被 NodeRestriction 准入插件允许或禁止。

将来的版本可能会增加其他限制，以确保 kubelet 具有正常运行所需的最小权限集。

OwnerReferencesPermissionEnforcement

该准入控制器保护对 metadata.ownerReferences 对象的访问，以便只有对该对象具有 “删除” 权限的用户才能对其进行更改。 该准入控制器还保护对 metadata.ownerReferences[x].blockOwnerDeletion 对象的访问， 以便只有对所引用的 属主（owner） 的 finalizers 子资源具有 “更新” 权限的用户才能对其进行更改。

PersistentVolumeClaimResize

该准入控制器检查传入的 PersistentVolumeClaim 调整大小请求，对其执行额外的验证操作。

说明：

对调整卷大小的支持是一种 Alpha 特性。管理员必须将特性门控 ExpandPersistentVolumes 设置为 true 才能启用调整大小。

启用 ExpandPersistentVolumes 特性门控之后，建议将 PersistentVolumeClaimResize 准入控制器也启用。除非 PVC 的 StorageClass 明确地将 allowVolumeExpansion 设置为 true 来显式启用调整大小。否则，默认情况下该准入控制器会阻止所有对 PVC 大小的调整。

例如：由以下 StorageClass 创建的所有 PersistentVolumeClaim 都支持卷容量扩充：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gluster-vol-default
provisioner: kubernetes.io/glusterfs
parameters:
  resturl: "http://192.168.10.100:8080"
  restuser: ""
  secretNamespace: ""
  secretName: ""
allowVolumeExpansion: true

关于持久化卷申领的更多信息，请参见 PersistentVolumeClaims。

PersistentVolumeLabel

该准入控制器会自动将区（region）或区域（zone）标签附加到由云提供商（如 GCE、AWS） 定义的 PersistentVolume。这有助于确保 Pod 和 PersistentVolume 位于相同的区或区域。 如果准入控制器不支持为 PersistentVolumes 自动添加标签，那你可能需要手动添加标签， 以防止 Pod 挂载其他区域的卷。 PersistentVolumeLabel 已被废弃，标记持久卷已由 云管理控制器接管。 从 1.11 开始，默认情况下禁用此准入控制器。

PodNodeSelector

该准入控制器通过读取名字空间注解和全局配置，来为名字空间中可以使用的节点选择器 设置默认值并实施限制。

配置文件格式

PodNodeSelector 使用配置文件来设置后端行为的选项。 请注意，配置文件格式将在将来某个版本中改为版本化文件。 该文件可以是 JSON 或 YAML，格式如下：

podNodeSelectorPluginConfig:
 clusterDefaultNodeSelector: name-of-node-selector
 namespace1: name-of-node-selector
 namespace2: name-of-node-selector

基于提供给 API 服务器命令行标志 --admission-control-config-file 的文件名， 从文件中引用 PodNodeSelector 配置文件：

• apiserver.config.k8s.io/v1
• apiserver.k8s.io/v1alpha1

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: PodNodeSelector
  path: podnodeselector.yaml
...

# 在 v1.17 中废弃，以鼓励使用 apiserver.config.k8s.io/v1
apiVersion: apiserver.k8s.io/v1alpha1
kind: AdmissionConfiguration
plugins:
- name: PodNodeSelector
  path: podnodeselector.yaml
...

配置注解格式

PodNodeSelector 使用键为 scheduler.alpha.kubernetes.io/node-selector 的注解 为名字空间设置节点选择算符。

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    scheduler.alpha.kubernetes.io/node-selector: name-of-node-selector
  name: namespace3

内部行为

该准入控制器行为如下：

1. 如果 Namespace 的注解带有键 scheduler.alpha.kubernetes.io/node-selector， 则将其值用作节点选择算符。
2. 如果名字空间缺少此类注解，则使用 PodNodeSelector 插件配置文件中定义的 clusterDefaultNodeSelector 作为节点选择算符。
3. 评估 Pod 节点选择算符和名字空间节点选择算符是否存在冲突。存在冲突将导致拒绝。
4. 评估 Pod 节点选择算符和特定于名字空间的被允许的选择算符所定义的插件配置文件是否存在冲突。 存在冲突将导致拒绝。

说明：

PodNodeSelector 允许 Pod 强制在特定标签的节点上运行。 另请参阅 PodTolerationRestriction 准入插件，该插件可防止 Pod 在特定污点的节点上运行。

PodSecurityPolicy

此准入控制器负责在创建和修改 Pod 时根据请求的安全上下文和可用的 Pod 安全策略确定是否可以执行请求。

查看 Pod 安全策略文档 了解更多细节。

PodTolerationRestriction

准入控制器 PodTolerationRestriction 检查 Pod 的容忍度与其名字空间的容忍度之间 是否存在冲突。如果存在冲突，则拒绝 Pod 请求。 然后，它将名字空间的容忍度合并到 Pod 的容忍度中，之后根据名字空间的容忍度 白名单检查所得到的容忍度结果。如果检查成功，则将接受 Pod 请求，否则拒绝该请求。

如果 Pod 的名字空间没有任何关联的默认容忍度或容忍度白名单，则使用集群级别的 默认容忍度或容忍度白名单（如果有的话）。

名字空间的容忍度通过注解健 scheduler.alpha.kubernetes.io/defaultTolerations 来设置。可接受的容忍度可以通过 scheduler.alpha.kubernetes.io/tolerationsWhitelist 注解键来添加。

名字空间注解的示例：

apiVersion: v1
kind: Namespace
metadata:
  name: apps-that-need-nodes-exclusively
  annotations:
    scheduler.alpha.kubernetes.io/defaultTolerations: '[{"operator": "Exists", "effect": "NoSchedule", "key": "dedicated-node"}]'
    scheduler.alpha.kubernetes.io/tolerationsWhitelist: '[{"operator": "Exists", "effect": "NoSchedule", "key": "dedicated-node"}]'

优先级

优先级准入控制器使用 priorityClassName 字段并用整型值填充优先级。 如果找不到优先级，则拒绝 Pod。

ResourceQuota

该准入控制器会监测传入的请求，并确保它不违反任何一个 Namespace 中的 ResourceQuota 对象中枚举出来的约束。 如果你在 Kubernetes 部署中使用了 ResourceQuota，你必须使用这个准入控制器来强制 执行配额限制。

请查看 resourceQuota 设计文档和 Resource Quota 例子 了解更多细节。

RuntimeClass

+

如果你开启 PodOverhead 特性门控, 并且通过 Pod 开销 配置来定义一个 RuntimeClass，这个准入控制器会检查新的 Pod。 当启用的时候，这个准入控制器会拒绝任何 overhead 字段已经设置的 Pod。 对于配置了 RuntimeClass 并在其 .spec 中选定 RuntimeClass 的 Pod， 此准入控制器会根据相应 RuntimeClass 中定义的值为 Pod 设置 .spec.overhead。

说明： Pod 的 .spec.overhead 字段和 RuntimeClass 的 .overhead 字段均为处于 beta 版本。 如果你未启用 PodOverhead 特性门控，则所有 Pod 均被视为未设置 .spec.overhead。

详情请参见 Pod 开销。

SecurityContextDeny

该准入控制器将拒绝任何试图设置特定提升 SecurityContext 字段的 Pod，正如任务 为 Pod 或 Container 配置安全上下文 中所展示的那样。 如果集群没有使用 Pod 安全策略 来限制安全上下文所能获取的值集，那么应该启用这个功能。

ServiceAccount

此准入控制器实现了 ServiceAccount 的自动化。 如果你打算使用 Kubernetes 的 ServiceAccount 对象，我们强烈建议你使用这个准入控制器。

StorageObjectInUseProtection

StorageObjectInUseProtection 插件将 kubernetes.io/pvc-protection 或 kubernetes.io/pv-protection finalizers 添加到新创建的持久化卷声明（PVC） 或持久化卷（PV）中。 如果用户尝试删除 PVC/PV，除非 PVC/PV 的保护控制器移除 finalizers，否则 PVC/PV 不会被删除。 有关更多详细信息，请参考 保护使用中的存储对象。

TaintNodesByCondition

该准入控制器为新创建的节点添加 NotReady 和 NoSchedule 污点。 这些污点能够避免一些竞态条件的发生，这类静态条件可能导致 Pod 在更新节点污点以准确 反映其所报告状况之前，就被调度到新节点上。

ValidatingAdmissionWebhook

该准入控制器调用与请求匹配的所有验证 Webhook。 匹配的 Webhook 将被并行调用。如果其中任何一个拒绝请求，则整个请求将失败。 该准入控制器仅在验证（Validating）阶段运行；与 MutatingAdmissionWebhook 准入控制器 所调用的 Webhook 相反，它调用的 Webhook 应该不会使对象出现变更。

如果以此方式调用的 Webhook 有其它作用（如，降低配额），则它必须具有协调机制。 这是因为无法保证后续的 Webhook 或其他有效的准入控制器都允许请求完成。

如果你禁用了 ValidatingAdmissionWebhook，还必须通过 --runtime-config 标志来禁用 admissionregistration.k8s.io/v1 组/版本中的 ValidatingWebhookConfiguration 对象（默认情况下在 1.9 版和更高版本中均处于启用状态）。

有推荐的准入控制器吗？

有。推荐使用的准入控制器默认情况下都处于启用状态 （请查看这里）。 因此，你无需显式指定它们。 你可以使用 --enable-admission-plugins 标志（ 顺序不重要 ）来启用默认设置以外的其他准入控制器。

说明：

--admission-control 在 1.10 中已废弃，由 --enable-admission-plugins 取代。

4.5 - 动态准入控制

除了内置的 admission 插件， 准入插件可以作为扩展独立开发，并以运行时所配置的 Webhook 的形式运行。 此页面描述了如何构建、配置、使用和监视准入 Webhook。

什么是准入 Webhook？

准入 Webhook 是一种用于接收准入请求并对其进行处理的 HTTP 回调机制。 可以定义两种类型的准入 webhook，即 验证性质的准入 Webhook 和 修改性质的准入 Webhook。 修改性质的准入 Webhook 会先被调用。它们可以更改发送到 API 服务器的对象以执行自定义的设置默认值操作。

在完成了所有对象修改并且 API 服务器也验证了所传入的对象之后， 验证性质的 Webhook 会被调用，并通过拒绝请求的方式来强制实施自定义的策略。

说明： 如果准入 Webhook 需要保证它们所看到的是对象的最终状态以实施某种策略。 则应使用验证性质的准入 Webhook，因为对象被修改性质 Webhook 看到之后仍然可能被修改。

尝试准入 Webhook

准入 Webhook 本质上是集群控制平面的一部分。你应该非常谨慎地编写和部署它们。 如果你打算编写或者部署生产级准入 webhook，请阅读用户指南以获取相关说明。 在下文中，我们将介绍如何快速试验准入 Webhook。

先决条件

• 确保 Kubernetes 集群版本至少为 v1.16（以便使用 admissionregistration.k8s.io/v1 API） 或者 v1.9 （以便使用 admissionregistration.k8s.io/v1beta1 API）。

• 确保启用 MutatingAdmissionWebhook 和 ValidatingAdmissionWebhook 控制器。 这里 是一组推荐的 admission 控制器，通常可以启用。

• 确保启用了 admissionregistration.k8s.io/v1beta1 API。

编写一个准入 Webhook 服务器

请参阅 Kubernetes e2e 测试中的 admission webhook 服务器 的实现。webhook 处理由 apiserver 发送的 AdmissionReview 请求，并且将其决定作为 AdmissionReview 对象以相同版本发送回去。

有关发送到 webhook 的数据的详细信息，请参阅 webhook 请求。

要获取来自 webhook 的预期数据，请参阅 webhook 响应。

示例准入 Webhook 服务器置 ClientAuth 字段为空，默认为 NoClientCert 。这意味着 webhook 服务器不会验证客户端的身份，认为其是 apiservers。 如果你需要双向 TLS 或其他方式来验证客户端，请参阅如何对 apiservers 进行身份认证。

部署准入 Webhook 服务

e2e 测试中的 webhook 服务器通过 deployment API 部署在 Kubernetes 集群中。该测试还将创建一个 service 作为 webhook 服务器的前端。参见相关代码。

你也可以在集群外部署 webhook。这样做需要相应地更新你的 webhook 配置。

即时配置准入 Webhook

你可以通过 ValidatingWebhookConfiguration 或者 MutatingWebhookConfiguration 动态配置哪些资源要被哪些准入 Webhook 处理。

以下是一个 ValidatingWebhookConfiguration 示例，mutating webhook 配置与此类似。有关每个配置字段的详细信息，请参阅 webhook 配置 部分。

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "pod-policy.example.com"
webhooks:
- name: "pod-policy.example.com"
  rules:
  - apiGroups:   [""]
    apiVersions: ["v1"]
    operations:  ["CREATE"]
    resources:   ["pods"]
    scope:       "Namespaced"
  clientConfig:
    service:
      namespace: "example-namespace"
      name: "example-service"
    caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle containing the CA that signed the webhook's serving certificate>...tLS0K"
  admissionReviewVersions: ["v1", "v1beta1"]
  sideEffects: None
  timeoutSeconds: 5

# 1.16 中被淘汰，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
metadata:
  name: "pod-policy.example.com"
webhooks:
- name: "pod-policy.example.com"
  rules:
  - apiGroups:   [""]
    apiVersions: ["v1"]
    operations:  ["CREATE"]
    resources:   ["pods"]
    scope:       "Namespaced"
  clientConfig:
    service:
      namespace: "example-namespace"
      name: "example-service"
    caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle containing the CA that signed the webhook's serving certificate>...tLS0K"
  admissionReviewVersions: ["v1beta1"]
  timeoutSeconds: 5

scope 字段指定是仅集群范围的资源（Cluster）还是名字空间范围的资源资源（Namespaced）将与此规则匹配。* 表示没有范围限制。

说明： 当使用 clientConfig.service 时，服务器证书必须对 <svc_name>.<svc_namespace>.svc 有效。

说明： 对于使用 admissionregistration.k8s.io/v1 创建的 webhook 而言，其 webhook 调用的默认超时是 10 秒； 对于使用 admissionregistration.k8s.io/v1beta1 创建的 webhook 而言，其默认超时是 30 秒。 从 kubernetes 1.14 开始，可以设置超时。建议对 webhooks 设置较短的超时时间。 如果 webhook 调用超时，则根据 webhook 的失败策略处理请求。

当 apiserver 收到与 rules 相匹配的请求时，apiserver 按照 clientConfig 中指定的方式向 webhook 发送一个 admissionReview 请求。

创建 webhook 配置后，系统将花费几秒钟使新配置生效。

对 apiservers 进行身份认证

如果你的 webhook 需要身份验证，则可以将 apiserver 配置为使用基本身份验证、持有者令牌或证书来向 webhook 提供身份证明。完成此配置需要三个步骤。

• 启动 apiserver 时，通过 --admission-control-config-file 参数指定准入控制配置文件的位置。

• 在准入控制配置文件中，指定 MutatingAdmissionWebhook 控制器和 ValidatingAdmissionWebhook 控制器应该读取凭据的位置。 凭证存储在 kubeConfig 文件中（是​​的，与 kubectl 使用的模式相同），因此字段名称为 kubeConfigFile。 以下是一个准入控制配置文件示例：

• apiserver.config.k8s.io/v1
• apiserver.k8s.io/v1alpha1

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: ValidatingAdmissionWebhook
  configuration:
    apiVersion: apiserver.config.k8s.io/v1
    kind: WebhookAdmissionConfiguration
    kubeConfigFile: "<path-to-kubeconfig-file>"
- name: MutatingAdmissionWebhook
  configuration:
    apiVersion: apiserver.config.k8s.io/v1
    kind: WebhookAdmissionConfiguration
    kubeConfigFile: "<path-to-kubeconfig-file>"

# 1.17 中被淘汰，推荐使用 apiserver.config.k8s.io/v1
apiVersion: apiserver.k8s.io/v1alpha1
kind: AdmissionConfiguration
plugins:
- name: ValidatingAdmissionWebhook
  configuration:
    # 1.17 中被淘汰，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration
    apiVersion: apiserver.config.k8s.io/v1alpha1
    kind: WebhookAdmission
    kubeConfigFile: "<path-to-kubeconfig-file>"
- name: MutatingAdmissionWebhook
  configuration:
    # 1.17 中被淘汰，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration
    apiVersion: apiserver.config.k8s.io/v1alpha1
    kind: WebhookAdmission
    kubeConfigFile: "<path-to-kubeconfig-file>"

有关 AdmissionConfiguration 的更多信息，请参见 AdmissionConfiguration schema。 有关每个配置字段的详细信息，请参见 webhook 配置部分。

• 在 kubeConfig 文件中，提供证书凭据：

  apiVersion: v1
  kind: Config
  users:
  # 名称应设置为服务的 DNS 名称或配置了 Webhook 的 URL 的主机名（包括端口）。
  # 如果将非 443 端口用于服务，则在配置 1.16+ API 服务器时，该端口必须包含在名称中。
  #
  # 对于配置在默认端口（443）上与服务对话的 Webhook，请指定服务的 DNS 名称：
  # - name: webhook1.ns1.svc
  #   user: ...
  #
  # 对于配置在非默认端口（例如 8443）上与服务对话的 Webhook，请在 1.16+ 中指定服务的 DNS 名称和端口：
  # - name: webhook1.ns1.svc:8443
  #   user: ...
  # 并可以选择仅使用服务的 DNS 名称来创建第二节，以与 1.15 API 服务器版本兼容：
  # - name: webhook1.ns1.svc
  #   user: ...
  #
  # 对于配置为使用 URL 的 webhook，请匹配在 webhook 的 URL 中指定的主机（和端口）。
  # 带有 `url: https://www.example.com` 的 webhook：
  # - name: www.example.com
  #   user: ...
  #
  # 带有 `url: https://www.example.com:443` 的 webhook：
  # - name: www.example.com:443
  #   user: ...
  #
  # 带有 `url: https://www.example.com:8443` 的 webhook：
  # - name: www.example.com:8443
  #   user: ...
  #
  - name: 'webhook1.ns1.svc'
    user:
      client-certificate-data: "<pem encoded certificate>"
      client-key-data: "<pem encoded key>"
  # `name` 支持使用 * 通配符匹配前缀段。
  - name: '*.webhook-company.org'
    user:
      password: "<password>"
      username: "<name>"
  # '*' 是默认匹配项。
  - name: '*'
    user:
      token: "<token>"
  

当然，你需要设置 webhook 服务器来处理这些身份验证。

请求

向 Webhook 发送 POST 请求时，请设置 Content-Type: application/json 并对 admission.k8s.io API 组中的 AdmissionReview 对象进行序列化，将所得到的 JSON 作为请求的主体。

Webhook 可以在配置中的 admissionReviewVersions 字段指定可接受的 AdmissionReview 对象版本：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  admissionReviewVersions: ["v1", "v1beta1"]
  ...

# v1.16 中被淘汰，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  admissionReviewVersions: ["v1beta1"]
  ...

API 服务器将发送的是 admissionReviewVersions 列表中所支持的第一个 AdmissionReview 版本。如果 API 服务器不支持列表中的任何版本，则不允许创建配置。

如果 API 服务器遇到以前创建的 Webhook 配置，并且不支持该 API 服务器知道如何发送的任何 AdmissionReview 版本，则调用 Webhook 的尝试将失败，并依据失败策略进行处理。

此示例显示了 AdmissionReview 对象中包含的数据，该数据用于请求更新 apps/v1 Deployment 的 scale 子资源：

• admission.k8s.io/v1
• admission.k8s.io/v1beta1

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "request": {
    # 唯一标识此准入回调的随机 uid
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",

    # 传入完全正确的 group/version/kind 对象
    "kind": {"group":"autoscaling","version":"v1","kind":"Scale"},
    # 修改 resource 的完全正确的的 group/version/kind
    "resource": {"group":"apps","version":"v1","resource":"deployments"},
    # subResource（如果请求是针对 subResource 的）
    "subResource": "scale",

    # 在对 API 服务器的原始请求中，传入对象的标准 group/version/kind
    # 仅当 webhook 指定 `matchPolicy: Equivalent` 且将对 API 服务器的原始请求转换为 webhook 注册的版本时，这才与 `kind` 不同。
    "requestKind": {"group":"autoscaling","version":"v1","kind":"Scale"},
    # 在对 API 服务器的原始请求中正在修改的资源的标准 group/version/kind
    # 仅当 webhook 指定了 `matchPolicy：Equivalent` 并且将对 API 服务器的原始请求转换为 webhook 注册的版本时，这才与 `resource` 不同。
    "requestResource": {"group":"apps","version":"v1","resource":"deployments"},
    # subResource（如果请求是针对 subResource 的）
    # 仅当 webhook 指定了 `matchPolicy：Equivalent` 并且将对 API 服务器的原始请求转换为该 webhook 注册的版本时，这才与 `subResource` 不同。
    "requestSubResource": "scale",

    # 被修改资源的名称
    "name": "my-deployment",
    # 如果资源是属于名字空间（或者是名字空间对象），则这是被修改的资源的名字空间
    "namespace": "my-namespace",

    # 操作可以是 CREATE、UPDATE、DELETE 或 CONNECT
    "operation": "UPDATE",

    "userInfo": {
      # 向 API 服务器发出请求的经过身份验证的用户的用户名
      "username": "admin",
      # 向 API 服务器发出请求的经过身份验证的用户的 UID
      "uid": "014fbff9a07c",
      # 向 API 服务器发出请求的经过身份验证的用户的组成员身份
      "groups": ["system:authenticated","my-admin-group"],
      # 向 API 服务器发出请求的用户相关的任意附加信息
      # 该字段由 API 服务器身份验证层填充，并且如果 webhook 执行了任何 SubjectAccessReview 检查，则应将其包括在内。
      "extra": {
        "some-key":["some-value1", "some-value2"]
      }
    },

    # object 是被接纳的新对象。
    # 对于 DELETE 操作，它为 null。
    "object": {"apiVersion":"autoscaling/v1","kind":"Scale",...},
    # oldObject 是现有对象。
    # 对于 CREATE 和 CONNECT 操作，它为 null。
    "oldObject": {"apiVersion":"autoscaling/v1","kind":"Scale",...},
    # options 包含要接受的操作的选项，例如 meta.k8s.io/v CreateOptions、UpdateOptions 或 DeleteOptions。
    # 对于 CONNECT 操作，它为 null。
    "options": {"apiVersion":"meta.k8s.io/v1","kind":"UpdateOptions",...},

    # dryRun 表示 API 请求正在以 `dryrun` 模式运行，并且将不会保留。
    # 带有副作用的 Webhook 应该避免在 dryRun 为 true 时激活这些副作用。
    # 有关更多详细信息，请参见 http://k8s.io/docs/reference/using-api/api-concepts/#make-a-dry-run-request
    "dryRun": false
  }
}

{
  # v1.16 中被废弃，推荐使用 admission.k8s.io/v1
  "apiVersion": "admission.k8s.io/v1beta1",
  "kind": "AdmissionReview",
  "request": {
    # 唯一标识此准入回调的随机 uid
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",

    # 传入完全正确的 group/version/kind 对象
    "kind": {"group":"autoscaling","version":"v1","kind":"Scale"},
    # 修改 resource 的完全正确的的 group/version/kind
    "resource": {"group":"apps","version":"v1","resource":"deployments"},
    # subResource（如果请求是针对 subResource 的）
    "subResource": "scale",

    # 在对 API 服务器的原始请求中，传入对象的标准 group/version/kind。
    # 仅当 Webhook 指定了 `matchPolicy：Equivalent` 并且将对 API 服务器的原始请求转换为该 Webhook 注册的版本时，这与 `kind` 不同。
    # 仅由 v1.15+ API 服务器发送。
    "requestKind": {"group":"autoscaling","version":"v1","kind":"Scale"},
    # 在对 API 服务器的原始请求中正在修改的资源的标准 group/version/kind
    # 仅当 webhook 指定了 `matchPolicy：Equivalent` 并且将对 API 服务器的原始请求转换为 webhook 注册的版本时，这才与 `resource` 不同。
    # 仅由 v1.15+ API 服务器发送。
    "requestResource": {"group":"apps","version":"v1","resource":"deployments"},
    # subResource（如果请求是针对 subResource 的）
    # 仅当 webhook 指定了 `matchPolicy：Equivalent` 并且将对 API 服务器的原始请求转换为该 webhook 注册的版本时，这才与 `subResource` 不同。
    # 仅由 v1.15+ API 服务器发送。
    "requestSubResource": "scale",

    # 被修改资源的名称
    "name": "my-deployment",
    # 如果资源是属于名字空间（或者是名字空间对象），则这是被修改的资源的名字空间
    "namespace": "my-namespace",

    # 操作可以是 CREATE、UPDATE、DELETE 或 CONNECT
    "operation": "UPDATE",

    "userInfo": {
      # 向 API 服务器发出请求的经过身份验证的用户的用户名
      "username": "admin",
      # 向 API 服务器发出请求的经过身份验证的用户的 UID
      "uid": "014fbff9a07c",
      # 向 API 服务器发出请求的经过身份验证的用户的组成员身份
      "groups": ["system:authenticated","my-admin-group"],
      # 向 API 服务器发出请求的用户相关的任意附加信息
      # 该字段由 API 服务器身份验证层填充，并且如果 webhook 执行了任何 SubjectAccessReview 检查，则应将其包括在内。
      "extra": {
        "some-key":["some-value1", "some-value2"]
      }
    },

    # object 是被接纳的新对象。
    # 对于 DELETE 操作，它为 null。
    "object": {"apiVersion":"autoscaling/v1","kind":"Scale",...},
    # oldObject 是现有对象。
    # 对于 CREATE 和 CONNECT 操作（对于 v1.15.0 之前版本的 API 服务器中的 DELETE 操作），它为 null。
    "oldObject": {"apiVersion":"autoscaling/v1","kind":"Scale",...},
    # options 包含要接受的操作的选项，例如 meta.k8s.io/v CreateOptions、UpdateOptions 或 DeleteOptions。
    # 对于 CONNECT 操作，它为 null。
    # 仅由 v1.15+ API 服务器发送。
    "options": {"apiVersion":"meta.k8s.io/v1","kind":"UpdateOptions",...},

    # dryRun 表示 API 请求正在以 `dryrun` 模式运行，并且将不会保留。
    # 带有副作用的 Webhook 应该避免在 dryRun 为 true 时激活这些副作用。
    # 有关更多详细信息，请参见 http://k8s.io/docs/reference/using-api/api-concepts/#make-a-dry-run-request
    "dryRun": false
  }
}

响应

Webhook 使用 HTTP 200 状态码、Content-Type: application/json 和一个包含 AdmissionReview 对象的 JSON 序列化格式来发送响应。该 AdmissionReview 对象与发送的版本相同，且其中包含的 response 字段已被有效填充。

response 至少必须包含以下字段：

• uid，从发送到 webhook 的 request.uid 中复制而来
• allowed，设置为 true 或 false

Webhook 允许请求的最简单响应示例：

• admission.k8s.io/v1
• admission.k8s.io/v1beta1

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true
  }
}

{
  "apiVersion": "admission.k8s.io/v1beta1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true
  }
}

Webhook 禁止请求的最简单响应示例：

• admission.k8s.io/v1
• admission.k8s.io/v1beta1

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false
  }
}

{
  "apiVersion": "admission.k8s.io/v1beta1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false
  }
}

当拒绝请求时，Webhook 可以使用 status 字段自定义 http 响应码和返回给用户的消息。 有关状态类型的详细信息，请参见 API 文档。 禁止请求的响应示例，它定制了向用户显示的 HTTP 状态码和消息：

• admission.k8s.io/v1
• admission.k8s.io/v1beta1

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false,
    "status": {
      "code": 403,
      "message": "You cannot do this because it is Tuesday and your name starts with A"
    }
  }
}

{
  "apiVersion": "admission.k8s.io/v1beta1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false,
    "status": {
      "code": 403,
      "message": "You cannot do this because it is Tuesday and your name starts with A"
    }
  }
}

当允许请求时，mutating准入 Webhook 也可以选择修改传入的对象。 这是通过在响应中使用 patch 和 patchType 字段来完成的。 当前唯一支持的 patchType 是 JSONPatch。 有关更多详细信息，请参见 JSON patch。 对于 patchType: JSONPatch，patch 字段包含一个以 base64 编码的 JSON patch 操作数组。

例如，设置 spec.replicas 的单个补丁操作将是 [{"op": "add", "path": "/spec/replicas", "value": 3}]。

如果以 Base64 形式编码，结果将是 W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0=

因此，添加该标签的 webhook 响应为：

• admission.k8s.io/v1
• admission.k8s.io/v1beta1

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true,
    "patchType": "JSONPatch",
    "patch": "W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0="
  }
}

{
  "apiVersion": "admission.k8s.io/v1beta1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true,
    "patchType": "JSONPatch",
    "patch": "W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0="
  }
}

Webhook 配置

要注册准入 Webhook，请创建 MutatingWebhookConfiguration 或 ValidatingWebhookConfiguration API 对象。

每种配置可以包含一个或多个 Webhook。如果在单个配置中指定了多个 Webhook，则应为每个 webhook 赋予一个唯一的名称。 这在 admissionregistration.k8s.io/v1 中是必需的，但是在使用 admissionregistration.k8s.io/v1beta1 时强烈建议使用， 以使生成的审核日志和指标更易于与活动配置相匹配。

每个 Webhook 定义以下内容。

匹配请求-规则

每个 webhook 必须指定用于确定是否应将对 apiserver 的请求发送到 webhook 的规则列表。 每个规则都指定一个或多个 operations、apiGroups、apiVersions 和 resources 以及资源的 scope：

• operations 列出一个或多个要匹配的操作。 可以是 CREATE、UPDATE、DELETE、CONNECT 或 * 以匹配所有内容。
• apiGroups 列出了一个或多个要匹配的 API 组。"" 是核心 API 组。"*" 匹配所有 API 组。
• apiVersions 列出了一个或多个要匹配的 API 版本。"*" 匹配所有 API 版本。
• resources 列出了一个或多个要匹配的资源。
  • "*" 匹配所有资源，但不包括子资源。
  • "*/*" 匹配所有资源，包括子资源。
  • "pods/*" 匹配 pod 的所有子资源。
  • "*/status" 匹配所有 status 子资源。
• scope 指定要匹配的范围。有效值为 "Cluster"、"Namespaced" 和 "*"。 子资源匹配其父资源的范围。在 Kubernetes v1.14+ 版本中才被支持。 默认值为 "*"，对应 1.14 版本之前的行为。
  • "Cluster" 表示只有集群作用域的资源才能匹配此规则（API 对象 Namespace 是集群作用域的）。
  • "Namespaced" 意味着仅具有名字空间的资源才符合此规则。
  • "*" 表示没有范围限制。

如果传入请求与任何 Webhook 规则的指定操作、组、版本、资源和范围匹配，则该请求将发送到 Webhook。

以下是可用于指定应拦截哪些资源的规则的其他示例。

匹配针对 apps/v1 和 apps/v1beta1 组中 deployments 和 replicasets 资源的 CREATE 或 UPDATE 请求：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["apps"]
    apiVersions: ["v1", "v1beta1"]
    resources: ["deployments", "replicasets"]
    scope: "Namespaced"
  ...

# v1.16 中被废弃，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["apps"]
    apiVersions: ["v1", "v1beta1"]
    resources: ["deployments", "replicasets"]
    scope: "Namespaced"
  ...

匹配所有 API 组和版本中的所有资源（但不包括子资源）的创建请求：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"
  ...

# v1.16 中被废弃，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"
  ...

匹配所有 API 组和版本中所有 status 子资源的更新请求：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"
  ...

# v1.16 中被废弃，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"
  ...

匹配请求：objectSelector

在版本 v1.15+ 中, 通过指定 objectSelector，Webhook 能够根据 可能发送的对象的标签来限制哪些请求被拦截。 如果指定，则将对 objectSelector 和可能发送到 Webhook 的 object 和 oldObject 进行评估。如果两个对象之一与选择器匹配，则认为该请求已匹配。

空对象（对于创建操作而言为 oldObject，对于删除操作而言为 newObject）， 或不能带标签的对象（例如 DeploymentRollback 或 PodProxyOptions 对象） 被认为不匹配。

仅当选择使用 webhook 时才使用对象选择器，因为最终用户可以通过设置标签来 跳过准入 Webhook。

这个例子展示了一个 mutating webhook，它将匹配带有标签 foo:bar 的任何资源的 CREATE 的操作：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  objectSelector:
    matchLabels:
      foo: bar
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"
  ...

# v1.16 中被废弃，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  objectSelector:
    matchLabels:
      foo: bar
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"
  ...

有关标签选择器的更多示例，请参见标签。

匹配请求：namespaceSelector

通过指定 namespaceSelector，Webhook 可以根据具有名字空间的资源所处的 名字空间的标签来选择拦截哪些资源的操作。

namespaceSelector 根据名字空间的标签是否匹配选择器，决定是否针对具名字空间的资源 （或 Namespace 对象）的请求运行 webhook。 如果对象是除 Namespace 以外的集群范围的资源，则 namespaceSelector 标签无效。

本例给出的修改性质的 Webhook 将匹配到对名字空间中具名字空间的资源的 CREATE 请求， 前提是这些资源不含值为 "0" 或 "1" 的 "runlevel" 标签：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  namespaceSelector:
    matchExpressions:
    - key: runlevel
      operator: NotIn
      values: ["0","1"]
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "Namespaced"
  ...

# v1.16 中被废弃，推荐使用 admissionregistration.k8s.io/v1
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  namespaceSelector:
    matchExpressions:
    - key: runlevel
      operator: NotIn
      values: ["0","1"]
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "Namespaced"
  ...

此示例显示了一个验证性质的 Webhook，它将匹配到对某名字空间中的任何具名字空间的资源的 CREATE 请求，前提是该名字空间具有值为 "prod" 或 "staging" 的 "environment" 标签：

• admissionregistration.k8s.io/v1
• admissionregistration.k8s.io/v1beta1

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  namespaceSelector:
    matchExpressions:
    - key: environment
      operator: In
      values: ["prod","staging"]
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "Namespaced"
  ...