证书签名请求

FEATURE STATE: Kubernetes v1.19 [stable]

证书 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小时后自动删除

签名者

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

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

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

Kubernetes 签名者

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

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

   1. 信任分发：签名的证书将被 kube-apiserver 视为客户端证书。CA 证书包不通过任何其他方式分发。
   2. 许可的主体 — 没有主体限制，但审核人和签名者可以选择不批准或不签署。 某些主体，比如集群管理员级别的用户或组，因部署和安装方式不同而不同， 所以批准和签署之前需要进行额外仔细审查。 用来限制 system:masters 的 CertificateSubjectRestriction 准入插件默认处于启用状态， 但它通常不是集群中唯一的 cluster-admin 主体。
   3. 许可的 x509 扩展 - 允许 subjectAltName 和 key usage 扩展，弃用其他扩展。
   4. 许可的密钥用途 - 必须包含 []string{"client auth"}，但不能包含 []string{"digital signature", "key encipherment", "client auth"} 之外的键。
   5. 过期时间/证书有效期 - CSR 签名者和请求中的较小者。签名者负责检查证书的有效期正常且可接受。
   6. 允许/不允许 CA 位 - 不允许。

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

   1. 信任分发： 签名的证书将被 kube-apiserver 视为客户端证书。CA 证书包不通过任何其他方式分发。
   2. 许可的主体 - 组织名必须是 []string{"system:nodes"}，用户名以 "system:node:" 开头
   3. 许可的 x509 扩展 — 允许 key usage 扩展，禁用 subjectAltName 扩展，并删除其他扩展。
   4. 许可的密钥用途 - 必须是 []string{"key encipherment", "digital signature", "client auth"}
   5. 过期时间/证书有效期 - CSR 签名者或请求中的较小者。签名者负责检查证书的有效期正常且可接受。
   6. 允许/不允许 CA 位 - 不允许。

3. kubernetes.io/kubelet-serving: 签名服务证书，该服务证书被 kube-apiserver 视为有效的 kubelet 服务证书，但没有其他保证。kube-controller-manager 不会自动批准它。

   1. 信任分发 ：签名的证书必须被 kube-apiserver 认可，可有效的中止 kubelet 连接。CA 证书包不通过任何其他方式分发。
   2. 许可的主体 - 组织名必须是 []string{"system:nodes"}，用户名以"system:node:"开头
   3. 许可的 x509 扩展 — 允许 key usage、DNSName/IPAddress subjectAltName 等扩展， 禁止 EmailAddress、URI subjectAltName 等扩展，并丢弃其他扩展。 至少有一个 DNS 或 IP 的 SubjectAltName 存在。
   4. 许可的密钥用途 - 必须是 []string{"key encipherment", "digital signature", "client auth"}
   5. 过期时间/证书有效期 - CSR 签名者或请求中的较小者。
   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. 过期时间/证书有效期 - CSR 签名者或请求中的较小者。签名者负责检查证书的有效期正常且可接受。
   6. 允许/不允许 CA 位 - 不允许。

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

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

鉴权

授权创建 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> or <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
  resourceName:
  - 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 调用的证书头或通过 kubectl 提供出来。

创建私钥

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

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

创建申请证书的 Kubernetes 对象

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

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

需要注意的几点:

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

批准证书请求

使用 kubectl 创建 CSR 并批准。

获取 CSR 列表

kubectl get csr

批准 CRS

kubectl certificate approve john

取得证书

从 CSR 取得证书。

kubectl get csr/john -o yaml

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

创建角色和角色绑定

你已经拿到证书了。为了让这个用户能访问 Kubernetes 集群资源，现在就要创建 Role 和 Role Binding 了。

这是为这个新用户创建角色的示例脚本

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

这是为这个新用户创建角色绑定的示例脚本

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

添加到 KubeConfig

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

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

kubectl config set-credentials john --client-key=/home/vagrant/work/john.key --client-certificate=/home/vagrant/work/john.crt --embed-certs=true

然后，我们需要添加上下文

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

来测试一下，把 kubecontext 切换为 john

kubectl config use-context john

批准和驳回

控制平面的自动化批准

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