CertificateSigningRequest

CertificateSigningRequest 对象提供了一种机制，通过提交证书签名请求来获取 x509 证书，并使其异步获得批准和颁发。

apiVersion: certificates.k8s.io/v1

import "k8s.io/api/certificates/v1"

CertificateSigningRequest

CertificateSigningRequest 对象提供了一种机制，通过提交证书签名请求来获取 x509 证书，并使其异步获得批准和颁发。

Kubelet 使用此 API 获取

  1. 用于向 kube-apiserver 进行身份验证的客户端证书（使用 "kubernetes.io/kube-apiserver-client-kubelet" signerName）。
  2. 用于 TLS 端点的服务证书，kube-apiserver 可以安全地连接到这些端点（使用 "kubernetes.io/kubelet-serving" signerName）。

此 API 可用于请求客户端证书以向 kube-apiserver 进行身份验证（使用 "kubernetes.io/kube-apiserver-client" signerName），或从自定义的非 Kubernetes signer 获取证书。

  • apiVersion: certificates.k8s.io/v1

  • kind: CertificateSigningRequest

  • metadata (ObjectMeta)

  • spec (CertificateSigningRequestSpec)，必需

    spec 包含证书请求，并且创建后不可变。只有 request、signerName、expirationSeconds 和 usages 字段可以在创建时设置。其他字段由 Kubernetes 派生，用户不能修改。

  • status (CertificateSigningRequestStatus)

    status 包含关于请求是否被批准或拒绝的信息，以及由 signer 颁发的证书，或者指示 signer 失败的失败条件。

CertificateSigningRequestSpec

CertificateSigningRequestSpec 包含证书请求。

  • request ([]byte)，必需

    原子性：在合并期间将被替换

    request 包含一个 x509 证书签名请求，编码在 "CERTIFICATE REQUEST" PEM 块中。当序列化为 JSON 或 YAML 时，数据会额外进行 base64 编码。

  • signerName (string)，必需

    signerName 指示所请求的 signer，并且是一个限定名。

    对 CertificateSigningRequest 的 List/watch 请求可以使用 "spec.signerName=NAME" 字段选择器在此字段上进行过滤。

    众所周知的 Kubernetes signer 是

    1. "kubernetes.io/kube-apiserver-client"：颁发可用于向 kube-apiserver 进行身份验证的客户端证书。对该 signer 的请求从未由 kube-controller-manager 自动批准，可由 kube-controller-manager 中的 "csrsigning" 控制器颁发。
    2. "kubernetes.io/kube-apiserver-client-kubelet"：颁发 Kubelet 用于向 kube-apiserver 进行身份验证的客户端证书。对该 signer 的请求可由 kube-controller-manager 中的 "csrapproving" 控制器自动批准，并可由 kube-controller-manager 中的 "csrsigning" 控制器颁发。
    3. "kubernetes.io/kubelet-serving"：颁发 Kubelet 用于提供 TLS 端点的服务证书，kube-apiserver 可以安全地连接到这些端点。对该 signer 的请求从未由 kube-controller-manager 自动批准，并可由 kube-controller-manager 中的 "csrsigning" 控制器颁发。

    更多详情请参阅 https://k8s.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers

    也可以指定自定义的 signerNames。signer 定义

    1. 信任分发：如何分发信任（CA 捆绑包）。
    2. 允许的主体：以及请求不允许的主体时的行为。
    3. 请求中必需、允许或禁止的 x509 扩展（包括是否允许 subjectAltNames、允许的类型、允许值的限制）以及请求不允许的扩展时的行为。
    4. 必需、允许或禁止的密钥用途 / 扩展密钥用途。
    5. 过期/证书生命周期：是由 signer 固定还是由管理员配置。
    6. 是否允许请求 CA 证书。

  • expirationSeconds (int32)

    expirationSeconds 是请求的已颁发证书的有效期时长。证书 signer 可能会颁发具有不同有效期时长的证书，因此客户端必须检查已颁发证书中 notBefore 和 notAfter 字段之间的差值以确定实际时长。

    v1.22+ 中内置的众所周知 Kubernetes signer 实现将遵从此字段，前提是请求的时长不超过它们根据传递给 Kubernetes 控制器管理器 `--cluster-signing-duration` CLI 标志所允许的最大时长。

    出于各种原因，证书 signer 可能不会遵从此字段

    1. 不知道此字段的旧 signer（例如 v1.22 之前的内置实现）
    2. 配置的最大时长短于请求时长的 signer
    3. 配置的最小时长长于请求时长的 signer

    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 客户端证书的请求通常请求：“数字签名”、“密钥加密”、“客户端认证”。

    对 TLS 服务端证书的请求通常请求：“密钥加密”、“数字签名”、“服务端认证”。

    有效值包括：“签名”、“数字签名”、“内容承诺”、“密钥加密”、“密钥协商”、“数据加密”、“证书签名”、“CRL 签名”、“仅加密”、“仅解密”、“任意”、“服务端认证”、“客户端认证”、“代码签名”、“电子邮件保护”、“s/mime”、“ipsec 端系统”、“ipsec 隧道”、“ipsec 用户”、“时间戳”、“OCSP 签名”、“microsoft sgc”、“netscape sgc”

  • username (string)

    username 包含创建 CertificateSigningRequest 的用户的名称。由 API 服务器在创建时填充且不可变。

CertificateSigningRequestStatus

CertificateSigningRequestStatus 包含用于指示请求的批准/拒绝/失败状态以及已颁发证书的条件。

  • certificate ([]byte)

    原子性：在合并期间将被替换

    certificate 字段在存在 Approved 条件后由 signer 填充已颁发证书。此字段通过 /status 子资源设置。一旦填充，此字段不可变。

    如果证书签名请求被拒绝，则会添加类型为 "Denied" 的条件，并且此字段保持为空。如果 signer 无法颁发证书，则会添加类型为 "Failed" 的条件，并且此字段保持为空。

    验证要求

    1. certificate 必须包含一个或多个 PEM 块。
    2. 所有 PEM 块必须带有 "CERTIFICATE" 标签，不包含头部，并且编码数据必须是符合 RFC5280 第 4 节描述的 BER 编码的 ASN.1 Certificate 结构。
    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)，必需

      条件的 status，取值为 True、False、Unknown 之一。Approved、Denied 和 Failed 条件不能为 "False" 或 "Unknown"。

    • conditions.type (string)，必需

      条件的 type。已知条件包括 "Approved"（已批准）、"Denied"（已拒绝）和 "Failed"（失败）。

      通过 /approval 子资源添加 "Approved" 条件，表示请求已获批准，应由 signer 颁发。

      通过 /approval 子资源添加 "Denied" 条件，表示请求已被拒绝，不应由 signer 颁发。

      通过 /status 子资源添加 "Failed" 条件，表示 signer 未能颁发证书。

      Approved 和 Denied 条件互斥。Approved、Denied 和 Failed 条件一旦添加就不能移除。

      每种类型只允许一个条件。

    • conditions.lastTransitionTime (Time)

      lastTransitionTime 是条件上次从一种 status 转换到另一种 status 的时间。如果未设置，当添加新的条件类型或更改现有条件的 status 时，服务器会将其默认为当前时间。

      _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 是 CertificateSigningRequest 对象的集合

  • apiVersion: certificates.k8s.io/v1

  • kind: CertificateSigningRequestList

  • metadata (ListMeta)

  • items ([]CertificateSigningRequest)，必需

    items 是 CertificateSigningRequest 对象的集合

操作

get 读取指定的 CertificateSigningRequest

HTTP 请求

GET /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}

参数

  • name (在路径中): string，必需

    CertificateSigningRequest 的名称

  • pretty (在查询参数中): string

    pretty

响应

200 (CertificateSigningRequest): OK

401: 未授权

get 读取指定的 CertificateSigningRequest 的批准状态

HTTP 请求

GET /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval

参数

  • name (在路径中): string，必需

    CertificateSigningRequest 的名称

  • pretty (在查询参数中): string

    pretty

响应

200 (CertificateSigningRequest): OK

401: 未授权

get 读取指定的 CertificateSigningRequest 的状态

HTTP 请求

GET /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status

参数

  • name (在路径中): string，必需

    CertificateSigningRequest 的名称

  • pretty (在查询参数中): string

    pretty

响应

200 (CertificateSigningRequest): OK

401: 未授权

list 列出或监听 kind 为 CertificateSigningRequest 的对象

HTTP 请求

GET /apis/certificates.k8s.io/v1/certificatesigningrequests

参数

响应

200 (CertificateSigningRequestList): OK

401: 未授权

create 创建一个 CertificateSigningRequest

HTTP 请求

POST /apis/certificates.k8s.io/v1/certificatesigningrequests

参数

响应

200 (CertificateSigningRequest): OK

201 (CertificateSigningRequest): 已创建

202 (CertificateSigningRequest): 已接受

401: 未授权

update 替换指定的 CertificateSigningRequest

HTTP 请求

PUT /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}

参数

响应

200 (CertificateSigningRequest): OK

201 (CertificateSigningRequest): 已创建

401: 未授权

update 替换指定的 CertificateSigningRequest 的批准状态

HTTP 请求

PUT /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval

参数

响应

200 (CertificateSigningRequest): OK

201 (CertificateSigningRequest): 已创建

401: 未授权

update 替换指定的 CertificateSigningRequest 的状态

HTTP 请求

PUT /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status

参数

响应

200 (CertificateSigningRequest): OK

201 (CertificateSigningRequest): 已创建

401: 未授权

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): 已创建

401: 未授权

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): 已创建

401: 未授权

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): 已创建

401: 未授权

delete 删除一个 CertificateSigningRequest

HTTP 请求

DELETE /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}

参数

响应

200 (Status): OK

202 (Status): 已接受

401: 未授权

deletecollection 删除 CertificateSigningRequest 集合

HTTP 请求

DELETE /apis/certificates.k8s.io/v1/certificatesigningrequests

参数

响应

200 (Status): OK

401: 未授权

此页面为自动生成。

如果您打算报告此页面的问题，请在您的问题描述中提及此页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

上次修改时间：2025 年 4 月 9 日下午 6:36（太平洋标准时间）：更新 v1.32 的 API 参考文档 (a3b579d035)