API 访问控制

• 1: 用户认证
• 2: 使用启动引导令牌（Bootstrap Tokens）认证
• 3: 证书和证书签名请求
• 4: 准入控制器参考
• 5: 动态准入控制
• 6: 管理服务账号
• 7: 鉴权概述
• 8: 使用 RBAC 鉴权
• 9: 使用 ABAC 鉴权
• 10: 使用 Node 鉴权
• 11: 从 PodSecurityPolicy 映射到 Pod 安全性标准
• 12: Webhook 模式
• 13: Kubelet 认证/鉴权
• 14: TLS 启动引导
• 15: 验证准入策略（ValidatingAdmissionPolicy）

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） 来认证 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），且该用户属于 "app1" 和 "app2" 两个用户组。

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

静态令牌文件

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

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

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

在请求中放入持有者令牌

当使用持有者令牌来对某 HTTP 客户端执行身份认证时，API 服务器希望看到一个名为 Authorization 的 HTTP 头，其值格式为 Bearer <token>。 持有者令牌必须是一个可以放入 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 编码的 x509 RSA 或 ECDSA 私钥或公钥， 用于验证 ServiceAccount 令牌。这样指定的文件可以包含多个密钥， 并且可以使用不同的文件多次指定此参数。若未指定，则使用 --tls-private-key-file 参数。
• --service-account-lookup 如果启用，则从 API 删除的令牌会被回收。

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

apiVersion: apps/v1 # 此 apiVersion 从 Kubernetes 1.9 开始可用
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 <名称> 命令。 此命令会在当前的名字空间中生成一个服务账号。

kubectl create serviceaccount jenkins

serviceaccount/jenkins created

创建相关联的令牌：

kubectl create token jenkins

eyJhbGciOiJSUzI1NiIsImtp...

所创建的令牌是一个已签名的 JWT 令牌。

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

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

OpenID Connect（OIDC）令牌

OpenID Connect 是一种 OAuth2 认证方式， 被某些 OAuth2 提供者支持，例如 Azure 活动目录、Salesforce 和 Google。 协议对 OAuth2 的主要扩充体现在有一个附加字段会和访问令牌一起返回， 这一字段称作 ID Token（ID 令牌）。 ID 令牌是一种由服务器签名的 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. 如果需要向 Kubernetes 控制面板执行身份认证，你必须使用 kubectl proxy 命令或者一个能够注入 id_token 的反向代理。

配置 API 服务器

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

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

Kubernetes 并未提供 OpenID Connect 的身份服务。 你可以使用现有的公共的 OpenID Connect 身份服务 （例如 Google 或者其他服务）。 或者，你也可以选择自己运行一个身份服务，例如 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，并且在 .kube/config 文件的 client_secret 中存放 refresh_token 和 id_token 的新值。

选项二：使用 --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 分钟。
• --authentication-token-webhook-version 决定是使用 authentication.k8s.io/v1beta1 还是 authenticationk8s.io/v1 版本的 TokenReview 对象从 Webhook 发送/接收信息。 默认为“v1beta1”。

配置文件使用 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-server
  name: webhook

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

要注意的是，Webhook API 对象和其他 Kubernetes API 对象一样， 也要受到同一版本兼容规则约束。 实现者应检查请求的 apiVersion 字段以确保正确的反序列化， 并且 必须 以与请求相同版本的 TokenReview 对象进行响应。

• authentication.k8s.io/v1
• authentication.k8s.io/v1beta1

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "TokenReview",
  "spec": {
   # 发送到 API 服务器的不透明持有者令牌
    "token": "014fbff9a07c...",
   
    # 提供令牌的服务器的受众标识符的可选列表。
    # 受众感知令牌验证器（例如，OIDC 令牌验证器）
    # 应验证令牌是否针对此列表中的至少一个受众，
    # 并返回此列表与响应状态中令牌的有效受众的交集。
    # 这确保了令牌对于向其提供给的服务器进行身份验证是有效的。
    # 如果未提供受众，则应验证令牌以向 Kubernetes API 服务器进行身份验证。
    "audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"]
  }
}

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "spec": {
    # 发送到 API 服务器的不透明匿名令牌
    "token": "014fbff9a07c...",
   
    # 提供令牌的服务器的受众标识符的可选列表。
    # 受众感知令牌验证器（例如，OIDC 令牌验证器）
    # 应验证令牌是否针对此列表中的至少一个受众，
    # 并返回此列表与响应状态中令牌的有效受众的交集。
    # 这确保了令牌对于向其提供给的服务器进行身份验证是有效的。
    # 如果未提供受众，则应验证令牌以向 Kubernetes API 服务器进行身份验证。
    "audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"]
  }
}

远程服务预计会填写请求的 status 字段以指示登录成功。 响应正文的 spec 字段被忽略并且可以省略。 远程服务必须使用它收到的相同 TokenReview API 版本返回响应。 持有者令牌的成功验证将返回：

• authentication.k8s.io/v1
• authentication.k8s.io/v1beta1

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "TokenReview",
  "status": {
    "authenticated": true,
    "user": {
      # 必要
      "username": "janedoe@example.com",
      # 可选
      "uid": "42",
      # 可选的组成员身份
      "groups": ["developers", "qa"],
      # 认证者提供的可选附加信息。
      # 此字段不可包含机密数据，因为这类数据可能被记录在日志或 API 对象中，
      # 并且可能传递给 admission webhook。
      "extra": {
        "extrafield1": [
          "extravalue1",
          "extravalue2"
        ]
      }
    },
    # 验证器可以返回的、可选的用户感知令牌列表，
    # 包含令牌对其有效的、包含于 `spec.audiences` 列表中的受众。
    # 如果省略，则认为该令牌可用于对 Kubernetes API 服务器进行身份验证。
    "audiences": ["https://myserver.example.com"]
  }
}

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": true,
    "user": {
      # 必要
      "username": "janedoe@example.com",
      # 可选
      "uid": "42",
      # 可选的组成员身份
      "groups": ["developers", "qa"],
      # 认证者提供的可选附加信息。
      # 此字段不可包含机密数据，因为这类数据可能被记录在日志或 API 对象中，
      # 并且可能传递给 admission webhook。
      "extra": {
        "extrafield1": [
          "extravalue1",
          "extravalue2"
        ]
      }
    },
    # 验证器可以返回的、可选的用户感知令牌列表，
    # 包含令牌对其有效的、包含于 `spec.audiences` 列表中的受众。
    # 如果省略，则认为该令牌可用于对 Kubernetes API 服务器进行身份验证。
    "audiences": ["https://myserver.example.com"]
  }
}

而不成功的请求会返回：

• authentication.k8s.io/v1
• authentication.k8s.io/v1beta1

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "TokenReview",
  "status": {
    "authenticated": false,
    # 可选地包括有关身份验证失败原因的详细信息。
    # 如果没有提供错误信息，API 将返回一个通用的 Unauthorized 消息。
    # 当 authenticated=true 时，error 字段被忽略。
    "error": "Credentials are expired"
  }
}

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": false,
    # 可选地包括有关身份验证失败原因的详细信息。
    # 如果没有提供错误信息，API 将返回一个通用的 Unauthorized 消息。
    # 当 authenticated=true 时，error 字段被忽略。
    "error": "Credentials are expired"
  }
}

身份认证代理

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 服务器会将与所给前缀匹配的头部字段过滤出来，去掉其前缀部分，将剩余部分转换为小写字符串， 并在必要时执行百分号解码后， 构造新的附加信息字段键名。原来的头部字段值直接作为附加信息字段的值。

例如，使用下面的配置：

--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 字符，且转换为百分号编码。
• Impersonate-Uid：一个唯一标识符，用来表示所伪装的用户。此头部可选。 如果设置，则要求 "Impersonate-User" 也存在。Kubernetes 对此字符串没有格式要求。

伪装带有用户组的用户时，所使用的伪装头部字段示例：

Impersonate-User: jane.doe@example.com
Impersonate-Group: developers
Impersonate-Group: admins

伪装带有 UID 和附加字段的用户时，所使用的伪装头部字段示例：

Impersonate-User: jane.doe@example.com
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
Impersonate-Uid: 06f6ce97-e2c5-4ab8-7ba5-7654dd08d52b

在使用 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

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

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

为了执行伪装，附加字段和所伪装的 UID 都位于 "authorization.k8s.io" apiGroup 中。 附加字段会被作为 userextras 资源的子资源来执行权限评估。 如果要允许用户为附加字段 “scopes” 和 UID 设置伪装头部，该用户需要被授予以下角色：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: scopes-and-uid-impersonator
rules:
# 可以设置 "Impersonate-Extra-scopes" 和 "Impersonate-Uid" 头部
- apiGroups: ["authentication.k8s.io"]
  resources: ["userextras/scopes", "uids"]
  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"]
  
  # 可以伪装 UID "06f6ce97-e2c5-4ab8-7ba5-7654dd08d52b"
  - apiGroups: ["authentication.k8s.io"]
    resources: ["uids"]
    verbs: ["impersonate"]
    resourceNames: ["06f6ce97-e2c5-4ab8-7ba5-7654dd08d52b"]

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 字段的一部分设置。

• client.authentication.k8s.io/v1
• client.authentication.k8s.io/v1beta1

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

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

      # 执行此插件时要设置的环境变量。可选字段。
      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

      # Exec 插件与标准输入 I/O 数据流之间的协议。如果协议无法满足，
      # 则插件无法运行并会返回错误信息。合法的值包括 "Never" （Exec 插件从不使用标准输入），
      # "IfAvailable" （Exec 插件希望在可以的情况下使用标准输入），
      # 或者 "Always" （Exec 插件需要使用标准输入才能工作）。必需字段。
      interactiveMode: Never
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

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

      # 解析 ExecCredentials 资源时使用的 API 版本。必需。
      # 插件返回的 API 版本必需与这里列出的版本匹配。
      #
      # 要与支持多个版本的工具（如 client.authentication.k8s.io/v1）集成，
      # 可以设置一个环境变量或者向工具传递一个参数标明 exec 插件所期望的版本，
      # 或者从 KUBERNETES_EXEC_INFO 环境变量的 ExecCredential 对象中读取版本信息。
      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

      # Exec 插件与标准输入 I/O 数据流之间的协议。如果协议无法满足，
      # 则插件无法运行并会返回错误信息。合法的值包括 "Never"（Exec 插件从不使用标准输入），
      # "IfAvailable" （Exec 插件希望在可以的情况下使用标准输入），
      # 或者 "Always" （Exec 插件需要使用标准输入才能工作）。可选字段。
      # 默认值为 "IfAvailable"。
      interactiveMode: Never
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/v1"
      interactiveMode: Never

输出和输出格式

所执行的命令会在 stdout 打印 ExecCredential 对象。 k8s.io/client-go 使用 status 中返回的凭据信息向 Kubernetes API 服务器执行身份认证。 所执行的命令会通过环境变量 KUBERNETES_EXEC_INFO 收到一个 ExecCredential 对象作为其输入。 此输入中包含类似于所返回的 ExecCredential 对象的预期 API 版本， 以及是否插件可以使用 stdin 与用户交互这类信息。

在交互式会话（即，某终端）中运行时，stdin 是直接暴露给插件使用的。 插件应该使用来自 KUBERNETES_EXEC_INFO 环境变量的 ExecCredential 输入对象中的 spec.interactive 字段来确定是否提供了 stdin。 插件的 stdin 需求（即，为了能够让插件成功运行，是否 stdin 是可选的、 必须提供的或者从不会被使用的）是通过 kubeconfig 中的 user.exec.interactiveMode 来声明的（参见下面的表格了解合法值）。 字段 user.exec.interactiveMode 在 client.authentication.k8s.io/v1beta1 中是可选的，在 client.authentication.k8s.io/v1 中是必需的。

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

• client.authentication.k8s.io/v1
• client.authentication.k8s.io/v1beta1

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

{
  "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）。

• client.authentication.k8s.io/v1
• client.authentication.k8s.io/v1beta1

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

{
  "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-----"
  }
}

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

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

• client.authentication.k8s.io/v1
• client.authentication.k8s.io/v1beta1

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

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

为了让 exec 插件能够获得特定与集群的信息，可以在 kubeconfig 中的 user.exec 设置 provideClusterInfo。 这一特定于集群的信息就会通过 KUBERNETES_EXEC_INFO 环境变量传递给插件。 此环境变量中的信息可以用来执行特定于集群的凭据获取逻辑。 下面的 ExecCredential 清单描述的是一个示例集群信息。

• client.authentication.k8s.io/v1
• client.authentication.k8s.io/v1beta1

{
  "apiVersion": "client.authentication.k8s.io/v1",
  "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"]
      }
    },
    "interactive": true
  }
}

{
  "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"]
      }
    },
    "interactive": true
  }
}

为客户端提供的对身份验证信息的 API 访问

如果集群启用了此 API，你可以使用 SelfSubjectReview API 来了解 Kubernetes 集群如何映射你的身份验证信息从而将你识别为某客户端。无论你是作为用户（通常代表一个真的人）还是作为 ServiceAccount 进行身份验证，这一 API 都可以使用。

SelfSubjectReview 对象没有任何可配置的字段。 Kubernetes API 服务器收到请求后，将使用用户属性填充 status 字段并将其返回给用户。

请求示例（主体将是 SelfSubjectReview）：

POST /apis/authentication.k8s.io/v1/selfsubjectreviews

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "SelfSubjectReview"
}

响应示例：

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "SelfSubjectReview",
  "status": {
    "userInfo": {
      "name": "jane.doe",
      "uid": "b6c7cfd4-f166-11ec-8ea0-0242ac120002",
      "groups": [
        "viewers",
        "editors",
        "system:authenticated"
      ],
      "extra": {
        "provider_id": ["token.company.example"]
      }
    }
  }
}

为了方便，Kubernetes 提供了 kubectl auth whoami 命令。 执行此命令将产生以下输出（但将显示不同的用户属性）：

• 简单的输出示例

  ATTRIBUTE         VALUE
  Username          jane.doe
  Groups            [system:authenticated]
  

• 包括额外属性的复杂示例

  ATTRIBUTE         VALUE
  Username          jane.doe
  UID               b79dbf30-0c6a-11ed-861d-0242ac120002
  Groups            [students teachers system:authenticated]
  Extra: skills     [reading learning]
  Extra: subjects   [math sports]
  

通过提供 output 标志，也可以打印结果的 JSON 或 YAML 表现形式：

• JSON
• YAML

{
  "apiVersion": "authentication.k8s.io/v1alpha1",
  "kind": "SelfSubjectReview",
  "status": {
    "userInfo": {
      "username": "jane.doe",
      "uid": "b79dbf30-0c6a-11ed-861d-0242ac120002",
      "groups": [
        "students",
        "teachers",
        "system:authenticated"
      ],
      "extra": {
        "skills": [
          "reading",
          "learning"
        ],
        "subjects": [
          "math",
          "sports"
        ]
      }
    }
  }
}

apiVersion: authentication.k8s.io/v1
kind: SelfSubjectReview
status:
  userInfo:
    username: jane.doe
    uid: b79dbf30-0c6a-11ed-861d-0242ac120002
    groups:
    - students
    - teachers
    - system:authenticated
    extra:
      skills:
      - reading
      - learning
      subjects:
      - math
      - sports

在 Kubernetes 集群中使用复杂的身份验证流程时，例如如果你使用 Webhook 令牌身份验证或 身份验证代理时， 此特性极其有用。

默认情况下，所有经过身份验证的用户都可以在 APISelfSubjectReview 特性被启用时创建 SelfSubjectReview 对象。 这是 system:basic-user 集群角色允许的操作。

接下来

• 阅读客户端认证参考文档（v1beta1）。
• 阅读客户端认证参考文档（v1）。

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 控制器来删除。

--controllers=*,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: 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。

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

3 - 证书和证书签名请求

Kubernetes 证书和信任包（trust bundle）API 可以通过为 Kubernetes API 的客户端提供编程接口， 实现 X.509 凭据的自动化制备， 从而请求并获取证书颁发机构 (CA) 发布的 X.509 证书。

此外，Kubernetes 还对分发信任包提供了实验性（Alpha）支持。

证书签名请求

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

请求签名流程

CertificateSigningRequest 资源类型允许客户端基于签名请求申请发放 X.509 证书。 CertificateSigningRequest 对象在 spec.request 字段中包含一个 PEM 编码的 PKCS#10 签名请求。 CertificateSigningRequest 使用 spec.signerName 字段标示签名者（请求的接收方）。 注意，spec.signerName 在 certificates.k8s.io/v1 之后的 API 版本是必填项。 在 Kubernetes v1.22 和以后的版本，客户可以可选地设置 spec.expirationSeconds 字段来为颁发的证书设定一个特定的有效期。该字段的最小有效值是 600，也就是 10 分钟。

创建完成的 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 小时后自动删除
• 挂起的请求：24 小时后自动删除
• 所有请求：在颁发的证书过期后自动删除

证书签名鉴权

授权创建 CertificateSigningRequest 和检索 CertificateSigningRequest：

• verbs（动词）: create、get、list、watch, group（组）：certificates.k8s.io， resource（资源）：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， resource（资源）：certificatesigningrequests
• verbs（动词）: update， group（组）：certificates.k8s.io， resource（资源）：certificatesigningrequests/approval
• verbs（动词）：approve， group（组）：certificates.k8s.io， resource（资源）：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/* 可用于为 “example.com” 域中的所有签名者授权
  verbs:
  - approve

授权签名 CertificateSigningRequest：

• verbs（动词）：get、list、watch， group（组）：certificates.k8s.io， resource（资源）：certificatesigningrequests
• verbs（动词）：update， group（组）：certificates.k8s.io， resource（资源）：certificatesigningrequests/status
• verbs（动词）：sign， group（组）：certificates.k8s.io， resource（资源）：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/* 可用于为 “example.com” 域中的所有签名者授权
  verbs:
  - sign

签名者

签名者抽象地代表可能签署或已签署安全证书的一个或多个实体。

任何要在特定集群以外提供的签名者都应该提供关于签名者工作方式的信息， 以便消费者可以理解这对于 CertifcateSigningRequests 和（如果启用的） ClusterTrustBundles 的意义。此类信息包括：

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

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

如果要让信任锚点（根证书）可用，应该将其与 CertificateSigningRequest 及其 status.certificate 字段分开处理。例如，你可以使用 ClusterTrustBundle。

PKCS#10 签名请求格式并没有一种标准的方法去设置证书的过期时间或者生命期。 因此，证书的过期时间或者生命期必须通过 CSR 对象的 spec.expirationSeconds 字段来设置。 当 spec.expirationSeconds 没有被指定时，内置的签名者默认使用 ClusterSigningDuration 配置选项 （kube-controller-manager 的命令行选项 --cluster-signing-duration），该选项的默认值设为 1 年。 当 spec.expirationSeconds 被指定时，spec.expirationSeconds 和 ClusterSigningDuration 中的最小值会被使用。

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 选项和 CSR 对象的 spec.expirationSeconds 字段（如有设置该字段）中的最小值。
   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"] 或 ["digital signature", "client auth"]。
   5. 过期时间/证书有效期：对于 kube-controller-manager 实现的签名者， 设置为 --cluster-signing-duration 选项和 CSR 对象的 spec.expirationSeconds 字段（如有设置该字段）中的最小值。
   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", "server auth"] 或 ["digital signature", "server auth"]。
   5. 过期时间/证书有效期：对于 kube-controller-manager 实现的签名者， 设置为 --cluster-signing-duration 选项和 CSR 对象的 spec.expirationSeconds 字段（如有设置该字段）中的最小值。
   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 选项和 CSR 对象的 spec.expirationSeconds 字段（如有设置该字段）中的最小值。
   6. 允许/不允许 CA 位 - 不允许。

kube-controller-manager 为每个内置签名者实现了控制平面签名。 注意：所有这些故障仅在 kube-controller-manager 日志中报告。

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

签名

控制平面签名者

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

基于 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..."

批准和驳回

签名者基于 CertificateSigningRequest 签发证书之前， 通常会检查 CSR 的签发是否已被批准。

控制平面的自动化批准

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 # 你可以将此字段设置为任意字符串
    type: Approved

驳回（Denied）的 CSR：

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 # 你可以将此字段设置为任意字符串
    type: Denied

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

集群信任包

ClusterTrustBundles 是一个作用域为集群的对象，向集群内的对象分发 X.509 信任锚点（根证书）。 此对象旨在与 CertificateSigningRequests 中的签名者概念协同工作。

ClusterTrustBundles 可以使用两种模式： 签名者关联和签名者未关联。

常见属性和验证

所有 ClusterTrustBundle 对象都对其 trustBundle 字段的内容进行强大的验证。 该字段必须包含一个或多个经 DER 序列化的 X.509 证书，每个证书都封装在 PEM CERTIFICATE 块中。 这些证书必须解析为有效的 X.509 证书。

诸如块间数据和块内标头之类的 PEM 特性在对象验证期间要么被拒绝，要么可能被对象的消费者忽略。 此外，消费者被允许使用自己的任意但稳定的排序方式重新排序 bundle 中的证书。

ClusterTrustBundle 对象应该在集群内被视为全局可读的。 如果集群使用 RBAC 鉴权， 则所有 ServiceAccount 都具有默认授权，允许它们 get、list 和 watch 所有 ClusterTrustBundle 对象。如果你使用自己的鉴权机制，并且在集群中启用了 ClusterTrustBundles，则应设置等效规则以使这些对象在集群内公开，使这些对象按预期工作。

如果你没有默认在集群中列出集群信任包的权限，则可以扮演具有访问权限的 ServiceAccount， 以查看可用的 ClusterTrustBundle：

kubectl get clustertrustbundles --as='system:serviceaccount:mynamespace:default'

签名者关联的 ClusterTrustBundles

签名者关联的 ClusterTrustBundles 与签名者名称关联，例如：

apiVersion: certificates.k8s.io/v1alpha1
kind: ClusterTrustBundle
metadata:
  name: example.com:mysigner:foo
spec:
  signerName: example.com/mysigner
  trustBundle: "<... PEM data ...>"

这些 ClusterTrustBundle 预期由集群中的特定签名者控制器维护，因此它们具有多个安全特性：

• 要创建或更新与一个签名者关联的 ClusterTrustBundle，你必须获准证明该签名者 （自定义鉴权动词 attest API 组 certificates.k8s.io；资源路径 signers）。 你可以为特定资源名称 <signerNameDomain>/<signerNamePath> 或匹配 <signerNameDomain>/* 等模式来配置鉴权。
• 与签名者关联的 ClusterTrustBundle 必须使用从其 spec.signerName 字段派生的前缀命名。 斜杠 (/) 被替换为英文冒号 (:)，最后追加一个英文冒号。后跟任意名称。 例如，签名者 example.com/mysigner 可以关联到 ClusterTrustBundle example.com:mysigner:<arbitrary-name>。

与签名者关联的 ClusterTrustBundle 通常通过组合签名者名称有关的 字段选择算符 或单独使用标签选择算符在工作负载中被消耗。

签名者未关联的 ClusterTrustBundles

签名者未关联的 ClusterTrustBundles 具有空白的 spec.signerName 字段，例如：

apiVersion: certificates.k8s.io/v1alpha1
kind: ClusterTrustBundle
metadata:
  name: foo
spec:
  # 未指定 signerName 所以该字段留空
  trustBundle: "<... PEM data ...>"

它们主要用于集群配置场景。每个与签名者未关联的 ClusterTrustBundle 都是一个独立的对象， 与签名者关联的 ClusterTrustBundle 的惯常分组行为形成了对比。

与签名者为关联的 ClusterTrustBundle 没有 attest 动词要求。 相反，你可以使用通常的机制（如基于角色的访问控制）直接控制对它们的访问。

为了将它们与与签名者关联的 ClusterTrustBundle 区分开来，与签名者未关联的 ClusterTrustBundle 的名称必须不包含英文冒号 (:)。

如何为用户签发证书

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

创建私钥

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

openssl genrsa -out myuser.key 2048
openssl req -new -key myuser.key -out myuser.csr -subj "/CN=myuser"

创建 CertificateSigningRequest

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

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

需要注意的几点:

• usage 字段必须是 'client auth'

• expirationSeconds 可以设置为更长（例如 864000 是十天）或者更短（例如 3600 是一个小时）

• request 字段是 CSR 文件内容的 base64 编码值。 要得到该值，可以执行命令

  cat myuser.csr | base64 | tr -d "\n"
  

批准 CertificateSigningRequest

使用 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 文件。

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

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

接下来

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

4 - 准入控制器参考

此页面提供准入控制器（Admission Controllers）的概述。

什么是准入控制插件？

准入控制器 是一段代码，它会在请求通过认证和鉴权之后、对象被持久化之前拦截到达 API 服务器的请求。

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

准入控制器限制创建、删除、修改对象的请求。 准入控制器也可以阻止自定义动作，例如通过 API 服务器代理连接到 Pod 的请求。 准入控制器不会 （也不能）阻止读取（get、watch 或 list）对象的请求。

Kubernetes 1.29 中的准入控制器由下面的列表组成， 并编译进 kube-apiserver 可执行文件，并且只能由集群管理员配置。 在该列表中，有两个特殊的控制器：MutatingAdmissionWebhook 和 ValidatingAdmissionWebhook。 它们根据 API 中的配置， 分别执行变更和验证准入控制 webhook。

准入控制阶段

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

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

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

为什么需要准入控制器？

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

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

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

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

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

怎么关闭准入控制器？

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

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

哪些插件是默认启用的？

要查看哪些插件是被启用的：

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

在 Kubernetes 1.29 中，默认启用的插件有：

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

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

AlwaysAdmit

类别：验证。

该准入控制器允许所有的 Pod 进入集群。此插件已被弃用，因其行为与没有准入控制器一样。

AlwaysDeny

类别：验证。

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

AlwaysPullImages

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

CertificateApproval

类别：验证。

此准入控制器获取审批 CertificateSigningRequest 资源的请求并执行额外的鉴权检查， 以确保针对设置了 spec.signerName 的 CertificateSigningRequest 资源而言， 审批请求的用户有权限对证书请求执行 审批 操作。

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

CertificateSigning

类别：验证。

此准入控制器监视对 CertificateSigningRequest 资源的 status.certificate 字段的更新请求， 并执行额外的鉴权检查，以确保针对设置了 spec.signerName 的 CertificateSigningRequest 资源而言， 签发证书的用户有权限对证书请求执行 签发 操作。

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

CertificateSubjectRestriction

类别：验证。

此准入控制器监视 spec.signerName 被设置为 kubernetes.io/kube-apiserver-client 的 CertificateSigningRequest 资源创建请求，并拒绝所有将 “group”（或 “organization attribute”） 设置为 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 分钟。

DenyServiceExternalIPs

类别：验证。

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

大多数用户根本不需要此特性，集群管理员应考虑将其禁用。 确实需要使用此特性的集群应考虑使用一些自定义策略来管理 externalIPs 的使用。 此准入控制器默认被禁用。

EventRateLimit

类别：验证。

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

• 启用 EventRateLimit 准入控制器；
• 在通过 API 服务器的命令行标志 --admission-control-config-file 设置的文件中， 引用 EventRateLimit 配置文件：

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

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

• Server：API 服务器收到的所有（创建或修改）Event 请求共享一个桶。
• 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

详情请参见 EventRateLimit 配置 API 文档（v1alpha1）。

此准入控制器默认被禁用。

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

在通过命令行标志 --admission-control-config-file 为 API 服务器提供的文件中， 引用 ImagePolicyWebhook 配置文件：

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

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

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

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

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

# 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 注解。

请求体示例：

{
  "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"
  }
}

远程服务将填充请求的 status 字段，并返回允许或不允许访问的响应。 响应体的 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。

使用注解进行扩展

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

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

• 在紧急情况下，请求破例覆盖某个策略。
• 从一个记录了破例的请求的工单（Ticket）系统得到的一个工单号码。
• 向策略服务器提供提示信息，用于提供镜像的 imageID，以方便它进行查找。

在任何情况下，注解都是由用户提供的，并不会被 Kubernetes 以任何方式进行验证。

LimitPodHardAntiAffinityTopology

类别：验证。

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

此准入控制器默认被禁用。

LimitRanger

类别：变更和验证。

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

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

MutatingAdmissionWebhook

类别：变更。

此准入控制器调用任何与请求匹配的变更（Mutating） Webhook。匹配的 Webhook 将被顺序调用。 每一个 Webhook 都可以自由修改对象。

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

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

如果你禁用了 MutatingAdmissionWebhook，那么还必须使用 --runtime-config 标志禁止 admissionregistration.k8s.io/v1 组/版本中的 MutatingWebhookConfiguration， 二者都是默认启用的。

谨慎编写和安装变更 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 对象。

不允许 kubelet 更新或删除 Node API 对象的污点。

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/ 为前缀的标签
  • node.kubernetes.io/ 为前缀的标签

以 kubernetes.io 或 k8s.io 为前缀的所有其他标签都限制 kubelet 使用，并且将来可能会被 NodeRestriction 准入插件允许或禁止。

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

OwnerReferencesPermissionEnforcement

类别：验证。

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

PersistentVolumeClaimResize

类别：验证。

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

建议启用 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

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

PersistentVolumeLabel

类别：变更。

此准入控制器会自动将由云提供商（如 Azure 或 GCP）定义的区（region）或区域（zone） 标签附加到 PersistentVolume 上。这有助于确保 Pod 和 PersistentVolume 位于相同的区或区域。 如果准入控制器不支持为 PersistentVolumes 自动添加标签，那你可能需要手动添加标签， 以防止 Pod 挂载其他区域的卷。PersistentVolumeLabel 已被弃用， 为持久卷添加标签的操作已由云管理控制器接管。

此准入控制器默认被禁用。

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 为 API 服务器提供的文件中， 需要引用 PodNodeSelector 配置文件：

apiVersion: apiserver.config.k8s.io/v1
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 节点选择算符和名字空间节点选择算符是否存在冲突。存在冲突将拒绝 Pod。
4. 评估 Pod 节点选择算符和特定于名字空间的被允许的选择算符所定义的插件配置文件是否存在冲突。 存在冲突将导致拒绝 Pod。

PodSecurity

类别：验证。

PodSecurity 准入控制器在新 Pod 被准入之前对其进行检查， 根据请求的安全上下文和 Pod 所在名字空间允许的 Pod 安全性标准的限制来确定新 Pod 是否应该被准入。

更多信息请参阅 Pod 安全性准入。

PodSecurity 取代了一个名为 PodSecurityPolicy 的旧准入控制器。

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 API 参考 和 Resource Quota 例子了解更多细节。

RuntimeClass

类别：变更和验证。

如果你所定义的 RuntimeClass 包含 Pod 开销， 这个准入控制器会检查新的 Pod。 被启用后，此准入控制器会拒绝所有已经设置了 overhead 字段的 Pod 创建请求。 对于配置了 RuntimeClass 并在其 .spec 中选定 RuntimeClass 的 Pod， 此准入控制器会根据相应 RuntimeClass 中定义的值为 Pod 设置 .spec.overhead。

详情请参见 Pod 开销。

SecurityContextDeny

类别：验证。

此准入控制器将拒绝任何尝试设置以下 SecurityContext 字段的 Pod：

• .spec.securityContext.supplementalGroups
• .spec.securityContext.seLinuxOptions
• .spec.securityContext.runAsUser
• .spec.securityContext.fsGroup
• .spec.(init)Containers[*].securityContext.seLinuxOptions
• .spec.(init)Containers[*].securityContext.runAsUser

有关此插件的更多历史背景，请参阅 Kubernetes 博客中这篇有关 PodSecurityPolicy 及其移除的文章： The birth of PodSecurityPolicy。 这篇文章详细地介绍了 PodSecurityPolicy 的历史背景以及 Pod 的 securityContext 字段的诞生。

ServiceAccount

类别：变更和验证。

此准入控制器实现了 ServiceAccount 的自动化。强烈推荐为 Kubernetes 项目启用此准入控制器。 如果你打算使用 Kubernetes 的 ServiceAccount 对象，你应启用这个准入控制器。

关于 kubernetes.io/enforce-mountable-secrets 注解：尽管注解的名称表明它只涉及 Secret 的挂载， 但其执行范围也扩展到 Pod 上下文中 Secret 的其他使用方式。 因此，确保所有引用的 Secret 在 ServiceAccount 中被正确指定是至关重要的。

StorageObjectInUseProtection

类别：变更。

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

TaintNodesByCondition

类别：变更。

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

ValidatingAdmissionPolicy

类别：验证。

此准入控制器针对传入的匹配请求实现 CEL 校验。当 validatingadmissionpolicy 和 admissionregistration.k8s.io/v1alpha1 特性门控组/版本被启用时， 此特性被启用。如果任意 ValidatingAdmissionPolicy 失败，则请求失败。

ValidatingAdmissionWebhook

类别：验证。

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

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

如果你禁用了 ValidatingAdmissionWebhook，还必须通过 --runtime-config 标志来禁用 admissionregistration.k8s.io/v1 组/版本中的 ValidatingWebhookConfiguration 对象。

有推荐的准入控制器吗？

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

5 - 动态准入控制

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

什么是准入 Webhook？

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

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

尝试准入 Webhook

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

先决条件

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

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

编写一个准入 Webhook 服务器

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

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

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

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

部署准入 Webhook 服务

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

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

即时配置准入 Webhook

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

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

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: <CA_BUNDLE>
  admissionReviewVersions: ["v1"]
  sideEffects: None
  timeoutSeconds: 5

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

当一个 API 服务器收到与 rules 相匹配的请求时， 该 API 服务器将按照 clientConfig 中指定的方式向 Webhook 发送一个 admissionReview 请求。

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

对 API 服务器进行身份认证

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

• 启动 API 服务器时，通过 --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 (v1) reference。 有关每个配置字段的详细信息，请参见 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 请求与响应

请求

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

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

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

创建 Webhook 配置时，admissionReviewVersions 是必填字段。 Webhook 必须支持至少一个当前和以前的 API 服务器都可以解析的 AdmissionReview 版本。

API 服务器将发送的是 admissionReviewVersions 列表中所支持的第一个 AdmissionReview 版本。如果 API 服务器不支持列表中的任何版本，则不允许创建配置。

如果 API 服务器遇到以前创建的 Webhook 配置，并且不支持该 API 服务器知道如何发送的任何 AdmissionReview 版本，则调用 Webhook 的尝试将失败，并依据失败策略进行处理。

此示例显示了 AdmissionReview 对象中包含的数据，该数据用于请求更新 apps/v1 Deployment 的 scale 子资源：

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/zh-cn/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 允许请求的最简单响应示例：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true
  }
}

Webhook 禁止请求的最简单响应示例：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false
  }
}

当拒绝请求时，Webhook 可以使用 status 字段自定义 http 响应码和返回给用户的消息。 有关状态类型的详细信息，请参见 API 文档。 禁止请求的响应示例，它定制了向用户显示的 HTTP 状态码和消息：

{
  "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"
    }
  }
}

当允许请求时，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 响应为：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true,
    "patchType": "JSONPatch",
    "patch": "W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0="
  }
}

准入 Webhook 可以选择性地返回在 HTTP Warning 头中返回给请求客户端的警告消息，警告代码为 299。 警告可以与允许或拒绝的准入响应一起发送。

如果你正在实现返回一条警告的 webhook，则：

• 不要在消息中包括 "Warning:" 前缀
• 使用警告消息描述该客户端进行 API 请求时会遇到或应意识到的问题
• 如果可能，将警告限制为 120 个字符

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true,
    "warnings": [
      "duplicate envvar entries specified with name MY_ENV",
      "memory request less than 4MB specified for container mycontainer, which will not start successfully"
    ]
  }
}

Webhook 配置

要注册准入 Webhook，请创建 MutatingWebhookConfiguration 或 ValidatingWebhookConfiguration API 对象。 MutatingWebhookConfiguration 或ValidatingWebhookConfiguration 对象的名称必须是有效的 DNS 子域名。

每种配置可以包含一个或多个 Webhook。如果在单个配置中指定了多个 Webhook，则应为每个 Webhook 赋予一个唯一的名称。 这是必需的，以使生成的审计日志和指标更易于与激活的配置相匹配。

每个 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" 和 "*"。 子资源匹配其父资源的范围。默认值为 "*"。

  • "Cluster" 表示只有集群作用域的资源才能匹配此规则（API 对象 Namespace 是集群作用域的）。
  • "Namespaced" 意味着仅具有名字空间的资源才符合此规则。
  • "*" 表示没有作用域限制。

如果传入请求与任何 Webhook rules 的指定 operations、groups、versions、 resources 和 scope 匹配，则该请求将发送到 Webhook。

以下是可用于指定应拦截哪些资源的规则的其他示例。

匹配针对 apps/v1 和 apps/v1beta1 组中 deployments 和 replicasets 资源的 CREATE 或 UPDATE 请求：

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"
  ...

匹配所有 API 组和版本中的所有资源（但不包括子资源）的创建请求：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    rules:
      - operations: ["CREATE"]
        apiGroups: ["*"]
        apiVersions: ["*"]
        resources: ["*"]
        scope: "*"

匹配所有 API 组和版本中所有 status 子资源的更新请求：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    rules:
      - operations: ["UPDATE"]
        apiGroups: ["*"]
        apiVersions: ["*"]
        resources: ["*/status"]
        scope: "*"

匹配请求：objectSelector

通过指定 objectSelector，Webhook 能够根据可能发送的对象的标签来限制哪些请求被拦截。 如果指定，则将对 objectSelector 和可能发送到 Webhook 的 object 和 oldObject 进行评估。如果两个对象之一与选择器匹配，则认为该请求已匹配。

空对象（对于创建操作而言为 oldObject，对于删除操作而言为 newObject）， 或不能带标签的对象（例如 DeploymentRollback 或 PodProxyOptions 对象） 被认为不匹配。

仅当选择使用 Webhook 时才使用对象选择器，因为最终用户可以通过设置标签来 跳过准入 Webhook。

这个例子展示了一个变更性质的 Webhook，它将匹配带有标签 foo:bar 的所有资源（但不包括子资源）的 CREATE 操作：

apiVersion: admissionregistration.k8s.io/v1
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" 标签：

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"

此示例显示了一个验证性质的 Webhook，它将匹配到对某名字空间中的任何具名字空间的资源的 CREATE 请求，前提是该名字空间具有值为 "prod" 或 "staging" 的 "environment" 标签：

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"

有关标签选择器的更多示例，请参见 标签。

匹配请求：matchPolicy

API 服务器可以通过多个 API 组或版本来提供对象。

例如，如果一个 Webhook 仅为某些 API 组/版本指定了规则（例如 apiGroups:["apps"], apiVersions:["v1","v1beta1"]），而修改资源的请求是通过另一个 API 组/版本（例如 extensions/v1beta1）发出的，该请求将不会被发送到 Webhook。

matchPolicy 允许 Webhook 定义如何使用其 rules 匹配传入的请求。 允许的值为 Exact 或 Equivalent。

• Exact 表示仅当请求与指定规则完全匹配时才应拦截该请求。
• Equivalent 表示如果某个请求意在修改 rules 中列出的资源， 即使该请求是通过其他 API 组或版本发起，也应拦截该请求。

在上面给出的示例中，仅为 apps/v1 注册的 Webhook 可以使用 matchPolicy：