--- api_metadata: apiVersion: "certificates.k8s.io/v1" import: "k8s.io/api/certificates/v1" kind: "CertificateSigningRequest" content_type: "api_reference" description: "CertificateSigningRequest 对象提供了一种通过提交证书签名请求并异步批准和颁发 x509 证书的机制。" title: CertificateSigningRequest weight: 4 --- `apiVersion: certificates.k8s.io/v1` `import "k8s.io/api/certificates/v1"` ## 证书签名请求 CertificateSigningRequest {#CertificateSigningRequest} CertificateSigningRequest 对象提供了一种通过提交证书签名请求并异步批准和颁发 x509 证书的机制。 kubelet 使用 CertificateSigningRequest API 来获取： 1. 向 kube-apiserver 进行身份认证的客户端证书（使用 “kubernetes.io/kube-apiserver-client-kubelet” signerName）。 2. kube-apiserver 可以安全连接到 TLS 端点的服务证书（使用 “kubernetes.io/kubelet-serving” signerName）。此 API 可用于请求客户端证书以向 kube-apiserver 进行身份验证（使用 “kubernetes.io/kube-apiserver-client” 签名者名称），或从自定义非 Kubernetes 签名者那里获取证书。

- **apiVersion**: certificates.k8s.io/v1 - **kind**: CertificateSigningRequest - **metadata** (}}">ObjectMeta) - **spec** (}}"> CertificateSigningRequestSpec)，必需 `spec` 包含证书请求，并且在创建后是不可变的。只有 `request`、`signerName`、`expirationSeconds` 和 `usages` 字段可以在创建时设置。其他字段由 Kubernetes 派生，用户无法修改。 - **status** (}}"> CertificateSigningRequestStatus) `status` 包含有关请求是被批准还是拒绝的信息，以及签名者颁发的证书或指示签名者失败的状况。 ## CertificateSigningRequestSpec {#CertificateSigningRequestSpec} CertificateSigningRequestSpec 包含证书请求。

- **request** ([]byte)，必需 `request` 包含一个在 “CERTIFICATE REQUEST” PEM 块中编码的 x509 证书签名请求。当序列化为 JSON 或 YAML 时，数据额外采用 base64 编码。 - **signerName** (string)，必需 `signerName` 表示请求的签名者，是一个限定名。 CertificateSigningRequests 的 list/watch 请求可以使用 `spec.signerName=NAME` 字段选择器进行过滤。众所周知的 Kubernetes 签名者有： 1. `kubernetes.io/kube-apiserver-client`：颁发客户端证书，用于向 kube-apiserver 进行身份验证。对此签名者的请求永远不会被 kube-controller-manager 自动批准，可以由 kube-controller-manager 中的 `csrsigning` 控制器颁发。 2. `kubernetes.io/kube-apiserver-client-kubelet`：颁发客户端证书，kubelet 用于向 kube-apiserver 进行身份验证。对此签名者的请求可以由 kube-controller-manager 中的 `csrapproving` 控制器自动批准，并且可以由 kube-controller-manager 中的 `csrsigning` 控制器颁发。 3. `kubernetes.io/kubelet-serving` 颁发服务证书，kubelet 用于服务 TLS 端点，kube-apiserver 可以安全的连接到这些端点。对此签名者的请求永远不会被 kube-controller-manager 自动批准，可以由 kube-controller-manager 中的 `csrsigning` 控制器颁发。更多详细信息，请访问 https://kubernetes.io/zh-cn/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers 也可以指定自定义 `signerName`。签名者定义如下： 1. 信任分发：信任（CA 证书包）是如何分发的。 2. 许可的主体：当请求不允许的主体时的行为。 3. 请求中必需、许可或禁止的 x509 扩展（包括是否允许 `subjectAltNames`、哪些类型、对允许值的限制）以及请求不允许的扩展时的行为。 4. 必需、许可或禁止的密钥用途/扩展密钥用途。 5. 过期/证书生命周期：是否由签名者确定，管理员可配置。 6. 是否允许申请 CA 证书。 - **expirationSeconds** (int32) `expirationSeconds` 是所颁发证书的所请求的有效期。证书签署者可以颁发具有不同有效期的证书，因此客户端必须检查颁发证书中 `notBefore` 和 `notAfter` 字段之间的增量以确定实际持续时间。众所周知的 Kubernetes 签名者在 v1.22+ 版本内实现将遵守此字段，只要请求的持续时间不大于最大持续时间，它们将遵守 Kubernetes 控制管理器的 `--cluster-signing-duration` CLI 标志。由于各种原因，证书签名者可能忽略此字段： 1. 不认识此字段的旧签名者(如 v1.22 版本之前的实现) 2. 配置的最大持续时间小于请求持续时间的签名者 3. 配置的最小持续时间大于请求持续时间的签名者 `expirationSeconds` 的最小有效值为 600，即 10 分钟。 - **extra** (map[string][]string) `extra` 包含创建 CertificateSigningRequest 的用户的额外属性。在创建时由 API 服务器填充，且不可变。 - **groups** ([]string) **原子性：将在合并过程中被替换** `groups` 包含创建 CertificateSigningRequest 的用户的组成员关系。在创建时由 API 服务器填充，且不可变。 - **uid** (string) `uid` 包含创建 CertificateSigningRequest 的用户的 UID。在创建时由 API 服务器填充，且不可变。 - **usages** ([]string) **原子性：将在合并期间被替换** `usages` 指定颁发证书中请求的一组密钥用途。 TLS 客户端证书的请求通常要求："digital signature"、"key encipherment"、"client auth"。 TLS 服务证书的请求通常要求："key encipherment"、"digital signature"、"server auth"。有效值： "signing"、"digital signature"、"content commitment"、 "key encipherment"、"key agreement"、"data encipherment"、 "cert sign"、"crl sign"、"encipher only"、"decipher only"、"any"、 "server auth"、"client auth"、 "code signing"、"email protection"、"s/mime"、 "ipsec end system"、"ipsec tunnel"、"ipsec user"、 "timestamping"、"ocsp signing"、"microsoft sgc"、"netscape sgc"。 - **username** (string) `username` 包含创建 CertificateSigningRequest 的用户名。在创建时由 API 服务器填充，且不可变。 ## CertificateSigningRequestStatus {#CertificateSigningRequestStatus} CertificateSigningRequestStatus 包含用于指示请求的批准/拒绝/失败状态和颁发证书的状况。

- **certificate** ([]byte) `certificate` 在出现 Approved 状况后，由签名者使用已颁发的证书填充。这个字段通过 `/status` 子资源设置。填充后，该字段将不可变。如果证书签名请求被拒绝，则添加类型为 `Denied` 的状况，并且保持该字段为空。如果签名者不能颁发证书，则添加类型为 `Failed` 的状况，并且保持该字段为空。验证要求： 1. 证书必须包含一个或多个 PEM 块。 2. 所有的 PEM 块必须有 `CERTIFICATE` 标签，不包含头和编码的数据，必须是由 BER 编码的 ASN.1 证书结构，如 RFC5280 第 4 节所述。 3. 非 PEM 内容可能出现在 `CERTIFICATE` PEM 块之前或之后，并且是未验证的，允许如 RFC7468 5.2 节中描述的解释性文本。如果存在多个 PEM 块，并且所请求的 `spec.signerName` 的定义没有另外说明，那么第一个块是颁发的证书，后续的块应该被视为中间证书并在 TLS 握手中呈现。证书编码为 PEM 格式。当序列化为 JSON 或 YAML 时，数据额外采用 base64 编码，它包括： ``` base64( -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- ) ``` - **conditions** ([]CertificateSigningRequestCondition) **Map：键类型的唯一值将在合并期间保留** 应用于请求的状况。已知的状况有 `"Approved"`、`"Denied"` 与 `"Failed"`。 **CertificateSigningRequestCondition 描述 CertificateSigningRequest 对象的状况。** - **conditions.status** (string)，必需状况的状态，`True`、`False`、`Unknown` 之一。`Approved`、`Denied` 与 `Failed` 的状况不可以是 `"False"` 或 `"Unknown"`。 - **conditions.type** (string)，必需状况的类型。已知的状况是 `"Approved"`、`"Denied"` 与 `"Failed"`。通过 `/approval` 子资源添加 `"Approved"` 状况，表示请求已被批准并且应由签名者颁发。通过 `/approval` 子资源添加 `"Denied"` 状况，指示请求被拒绝并且不应由签名者颁发。通过 `/status` 子资源添加 `"Failed"` 状况，表示签名者未能颁发证书。 `Approved` 和 `Denied` 状况是相互排斥的。`Approved`、`Denied` 和 `Failed` 状况一旦添加就无法删除。给定类型只允许设置一种状况。 - **conditions.lastTransitionTime** (Time) `lastTransitionTime` 是状况上一次从一种状态转换到另一种状态的时间。如果未设置，当添加新状况类型或更改现有状况的状态时，服务器默认为当前时间。 **Time 是 time.Time 的包装器，支持正确编码为 YAML 和 JSON。为 time 包提供的许多工厂方法提供了包装器。** - **conditions.lastUpdateTime** (Time) lastUpdateTime 是该状况最后一次更新的时间。 **Time 是 time.Time 的包装器，支持正确编组为 YAML 和 JSON。为 time 包提供的许多工厂方法提供了包装器。** - **conditions.message** (string) `message` 包含一个人类可读的消息，包含关于请求状态的详细信息。 - **conditions.reason** (string) `reason` 表示请求状态的简短原因。 ## CertificateSigningRequestList {#CertificateSigningRequestList} CertificateSigningRequestList 是 CertificateSigningRequest 对象的集合。

- **apiVersion**: certificates.k8s.io/v1 - **kind**: CertificateSigningRequestList - **metadata** (}}">ListMeta) - **items** ([]}}">CertificateSigningRequest)，必需 `items` 是 CertificateSigningRequest 对象的集合。 ## 操作 {#Operations}

### `get` 读取指定的 CertificateSigningRequest #### HTTP 请求 GET /apis/certificates.k8s.io/v1/certificatesigningrequests/{name} #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 401: Unauthorized ### `get` 读取指定 CertificateSigningRequest 的批准信息 #### HTTP 请求 GET /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 401: Unauthorized ### `get` 读取指定 CertificateSigningRequest 的状态 #### HTTP 请求 GET /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 401: Unauthorized ### `list` list 或 watch CertificateSigningRequest 类型的对象 #### HTTP 请求 GET /apis/certificates.k8s.io/v1/certificatesigningrequests #### 参数 - **allowWatchBookmarks** (**查询参数**): boolean }}">allowWatchBookmarks - **continue** (**查询参数**): string }}">continue - **fieldSelector** (**查询参数**): string }}">fieldSelector - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **sendInitialEvents** (**查询参数**): boolean }}">sendInitialEvents - **shardSelector** (**查询参数**): string }}">shardSelector - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds - **watch** (**查询参数**): boolean }}">watch #### 响应 200 (}}">CertificateSigningRequestList): OK 401: Unauthorized ### `create` 创建一个 CertificateSigningRequest #### HTTP 请求 POST /apis/certificates.k8s.io/v1/certificatesigningrequests #### 参数 - **body**: }}">CertificateSigningRequest，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 202 (}}">CertificateSigningRequest): Accepted 401: Unauthorized ### `update` 替换指定的 CertificateSigningRequest #### HTTP 请求 PUT /apis/certificates.k8s.io/v1/certificatesigningrequests/{name} #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">CertificateSigningRequest，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 401: Unauthorized ### `update` 替换对指定 CertificateSigningRequest 的批准信息 #### HTTP 请求 PUT /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">CertificateSigningRequest，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 401: Unauthorized ### `update` 替换指定 CertificateSigningRequest 的状态 #### HTTP 请求 PUT /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">CertificateSigningRequest，必需 - **dryRun** (*in query*): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 401: Unauthorized ### `patch` 部分更新指定的 CertificateSigningRequest #### HTTP 请求 PATCH /apis/certificates.k8s.io/v1/certificatesigningrequests/{name} #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">Patch，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **force** (**查询参数**): boolean }}">force - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 401: Unauthorized ### `patch` 部分更新指定 CertificateSigningRequest 的批准信息 #### HTTP 请求 PATCH /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">Patch，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **force** (**查询参数**): boolean }}">force - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 401: Unauthorized ### `patch` 部分更新指定 CertificateSigningRequest 的状态 #### HTTP 请求 PATCH /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">Patch，必需 - **dryRun** (**查询参数**): string }}">dryRun - **fieldManager** (**查询参数**): string }}">fieldManager - **fieldValidation** (**查询参数**): string }}">fieldValidation - **force** (**查询参数**): boolean }}">force - **pretty** (**查询参数**): string }}">pretty #### 响应 200 (}}">CertificateSigningRequest): OK 201 (}}">CertificateSigningRequest): Created 401: Unauthorized ### `delete` 删除一个 CertificateSigningRequest #### HTTP 请求 DELETE /apis/certificates.k8s.io/v1/certificatesigningrequests/{name} #### 参数 - **name** (**路径参数**): string，必需 CertificateSigningRequest 的名称。 - **body**: }}">DeleteOptions - **dryRun** (**查询参数**): string }}">dryRun - **gracePeriodSeconds** (**查询参数**): integer }}">gracePeriodSeconds - **ignoreStoreReadErrorWithClusterBreakingPotential** (**查询参数**): boolean }}">ignoreStoreReadErrorWithClusterBreakingPotential - **pretty** (**查询参数**): string }}">pretty - **propagationPolicy** (**查询参数**): string }}">propagationPolicy #### 响应 200 (}}">Status): OK 202 (}}">Status): Accepted 401: Unauthorized ### `deletecollection` 删除 CertificateSigningRequest 集合 #### HTTP 请求 DELETE /apis/certificates.k8s.io/v1/certificatesigningrequests #### 参数 - **body**: }}">DeleteOptions - **continue** (**查询参数**): string }}">continue - **dryRun** (**查询参数**): string }}">dryRun - **fieldSelector** (**查询参数**): string }}">fieldSelector - **gracePeriodSeconds** (**查询参数**): integer }}">gracePeriodSeconds - **ignoreStoreReadErrorWithClusterBreakingPotential** (**查询参数**): boolean }}">ignoreStoreReadErrorWithClusterBreakingPotential - **labelSelector** (**查询参数**): string }}">labelSelector - **limit** (**查询参数**): integer }}">limit - **pretty** (**查询参数**): string }}">pretty - **propagationPolicy** (**查询参数**): string }}">propagationPolicy - **resourceVersion** (**查询参数**): string }}">resourceVersion - **resourceVersionMatch** (**查询参数**): string }}">resourceVersionMatch - **sendInitialEvents** (**查询参数**): boolean }}">sendInitialEvents - **shardSelector** (**查询参数**): string }}">shardSelector - **timeoutSeconds** (**查询参数**): integer }}">timeoutSeconds #### 响应 200 (}}">Status): OK 401: Unauthorized