后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载本指南以 kubernetes-python 官方客户端中V1beta1PodCertificateRequestSpec模型为主线剖析 Pod 通过podCertificate投影卷向签名器signer申请证书时携带的完整请求载荷12 个字段的语义、类型约束、必填要求、签名算法与过期时间策略并结合仓库源码、OpenAPI 定义与CertificatesV1beta1Api调用链给出可直接运行的 Python 示例。读完本文你将能准确构造一个合法的 PodCertificateRequest 请求、理解proofOfPossession与stubPKCS10Request两个互斥字段的底层密码学机制并知晓签名器拒绝请求时的标准条件表达方式。背景PodCertificateRequest 与 Spec 模型的位置在 Kubernetes 中Pod 可以通过podCertificate投影卷申请由集群内签名器签发的证书。承载这一能力的新资源就是PodCertificateRequestAPI 组certificates.k8s.io本仓库对应v1beta1版本。Kubelet 使用该 API 实现podCertificate投影卷Pod 创建后kubelet 代表 Pod 提交一个证书请求签名器如kubernetes.io/kube-apiserver-client-pod审核并签发证书最终写入 Pod 的投影卷。在 kubernetes-python 官方客户端中该资源的 spec 部分由模型类V1beta1PodCertificateRequestSpec表示位于同步客户端kubernetes/client/models/v1beta1_pod_certificate_request_spec.py异步客户端aiokubernetes/aio/client/models/v1beta1_pod_certificate_request_spec.py对应的文档页由 Sphinx autodoc 从源码 docstring 自动渲染doc/source/kubernetes.aio.client.models.v1beta1_pod_certificate_request_spec.rst。模型类通过kubernetes.aio.client.models.__init__.py的__all__导出见 kubernetes/aio/client/models/init.py因此可直接通过from kubernetes.aio.client.models import V1beta1PodCertificateRequestSpec导入。父模型V1beta1PodCertificateRequest的构成见 kubernetes/aio/client/models/v1beta1_pod_certificate_request.pyapiVersion: str # certificates.k8s.io/v1beta1 kind: str # PodCertificateRequest metadata: V1ObjectMeta # 对象元数据 spec: V1beta1PodCertificateRequestSpec # 本文核心 status: V1beta1PodCertificateRequestStatus # 由签名器填充Spec的官方语义是描述证书请求且创建后所有字段均不可变All fields are immutable after creation。字段全景类型、必填性与 JSON 名称映射V1beta1PodCertificateRequestSpec共定义 12 个字段。模型基于 PydanticBaseModel构建每个字段同时支持驼峰式wire 名如nodeName与下划线式Python 名如node_name输入通过AliasChoices自动兼容。源码中openapi_types与attribute_map两张类变量表见 kubernetes/aio/client/models/v1beta1_pod_certificate_request_spec.py给出了完整映射Python 属性JSON 字段wire 名类型Python必填max_expiration_secondsmaxExpirationSecondsintStrictInt格式 int32否node_namenodeNamestrStrictStr是node_uidnodeUIDstr是pkix_public_keypkixPublicKeybytes否已弃用pod_namepodNamestr是pod_uidpodUIDstr是proof_of_possessionproofOfPossessionbytes否已弃用service_account_nameserviceAccountNamestr是service_account_uidserviceAccountUIDstr是signer_namesignerNamestr是stub_pkcs10_requeststubPKCS10Requestbytes是unverified_user_annotationsunverifiedUserAnnotationsDict[str, str]否必填项与 OpenAPI 定义scripts/swagger.json中v1beta1.PodCertificateRequestSpec的required列表完全一致共 8 个必填字段signerName、podName、podUID、serviceAccountName、serviceAccountUID、nodeName、nodeUID、stubPKCS10Request。模型的model_config源码第 224-230 行启用了validate_by_nameTrue、validate_by_aliasTrue、validate_assignmentTrue并设置extraforbid——即传入未定义的字段会直接报错这有助于在构造请求时尽早暴露拼写错误。身份绑定字段Pod、Node 与 ServiceAccountSpec 通过 6 个字符串字段将证书请求与运行上下文强绑定全部必填podName证书将被挂载进入的 Pod 名称。podUID该 Pod 的 UID。nodeNamePod 所调度到的节点名称。nodeUID该节点的 UID。serviceAccountNamePod 运行所用的 ServiceAccount 名称。serviceAccountUID该 ServiceAccount 的 UID。从设计意图看这些字段构成请求的身份上下文签名器可以据此校验请求者是否确实运行在指定 Pod 中、使用指定的 ServiceAccount从而防止证书被滥用或跨身份冒领。proofOfPossession字段进一步把持有私钥与Pod UID绑定见下文。证书生命周期控制maxExpirationSecondsmaxExpirationSecondsint可选是签名器签发证书的最大生命周期上限。源码 docstring 给出的完整约束与 swagger 定义一致省略时kube-apiserver 会将其设置为8640024 小时kube-apiserver 会拒绝**小于 36001 小时**的值最大允许值为786240091 天签名器实现可以签发任何短于maxExpirationSeconds的证书但不能短于 3600 秒1 小时——该下限由 kube-apiserver 强制kubernetes.io前缀的签名器永远不会签发超过 24 小时生命周期的证书。换言之客户端可以请求最长 91 天但内置签名器实际会收敛到 24 小时内。字段类型为StrictIntint32 格式构造时务必传整数。密钥与签名请求pkixPublicKey、proofOfPossession 与 stubPKCS10Request这三个字段构成证书请求的密码学核心且涉及版本演进需要重点理解。支持的公钥类型无论pkixPublicKey还是stubPKCS10Request其承载的公钥都必须是以下类型之一RSA3072、RSA4096、ECDSA P-256、ECDSA P-384、ECDSA P-521 或 ED25519。文档注明该列表未来可能扩展。签名器实现并不需要支持 kube-apiserver 与 kubelet 支持的全部密钥类型若签名器不支持某 PodCertificateRequest 使用的密钥类型它必须通过设置status.conditions中typeDenied、reasonUnsupportedKeyType的条目来拒绝请求并可在message字段中建议它支持的密钥类型。pkixPublicKey 与 proofOfPossession已弃用pkixPublicKeybytes可选以 PKIX 序列化格式表示的、签名器将为之签发证书的公钥。proofOfPossessionbytes可选证明请求方 kubelet 持有与pkixPublicKey对应私钥的凭证。其构造方式是用pkixPublicKey对应的私钥对 Pod UID 的 ASCII 字节进行签名kube-apiserver 会在 PodCertificateRequest 创建时校验该持有证明。不同密钥算法的签名规范源码 docstring 明确指出密钥类型签名算法RSARSASSA-PSSRFC 8017等价于 Gocrypto/rsa.SignPSSnil options对 Pod UID 的 ASCII 字节签名ECDSASEC 1 Version 2.0 描述等价于 Gocrypto/ecdsa.SignASN1ED25519ED25519 规范等价于 Gocrypto/ed25519.Sign注意这两个字段均标注Deprecated已弃用被stubPKCS10Request取代。若设置了stubPKCS10Request则这两个字段必须为空。签名器实现应改为从stubPKCS10Request中提取公钥。stubPKCS10Request现行机制stubPKCS10Requestbytes必填由 kubelet 使用主体私钥生成的PKCS#10 证书签名请求DER 序列化。大多数签名器实现会忽略 CSR 内容仅从中提取主体公钥API server 在准入admission阶段会自动验证 CSR 签名因此签名器无需重复验证。由 kubelet 生成的 CSR 内容完全是空的completely empty。其主体公钥同样必须为前述六种类型之一且不被签名器支持时按Denied/UnsupportedKeyType方式拒绝。bytes 类型与 Base64 校验源码中对pkix_public_key、proof_of_possession、stub_pkcs10_request三个字段都注册了field_validator(..., modebefore)见 v1beta1_pod_certificate_request_spec.py 第 150-175 行当传入字符串时会校验其是否为合法的 Base64 编码正则^(?:[A-Za-z0-9/]{4})*(?:[A-Za-z0-9/]{2}|[A-Za-z0-9/]{3})?$否则抛出ValueError。结合 swagger 中format: byte的类型定义可以确认这三个字段在 wire 协议上以 Base64 字符串传输在 Python 侧则映射为bytes。扩展元数据unverifiedUserAnnotationsunverifiedUserAnnotationsDict[str, str]可选允许 Pod 作者向签名器实现传递附加信息Kubernetes 不会以任何方式限制或校验这些元数据。约束要点键的校验规则与对象元数据metadata.annotations的注解校验一致但所有键必须带域名前缀domain-prefixed值没有额外限制但整个字段存在总体大小限制签名器应当在其文档中说明支持的键与值并对包含其不识别键的请求予以拒绝。这使得请求方可以在证书申请流程中携带业务上下文例如用途标识、申请方联系方式等供自定义签名器决策。模型 API序列化、反序列化与 JSON 互操作V1beta1PodCertificateRequestSpec继承了 kubernetes-python 生成模型的统一方法族所有方法均可在源码中直接查阅v1beta1_pod_certificate_request_spec.py方法作用to_json()输出使用 wire 名驼峰的 JSON 字符串from_json(json_str)从 JSON 字符串构造实例to_dict(serializeFalse)返回 dictserializeTrue时使用 wire 名驼峰键from_dict(obj)从 dict 构造实例自动兼容驼峰/下划线键内部经__preprocess_input_names归一化to_str()/__repr__()打印友好表示__eq__/__ne__基于to_dict()结果比较对象相等性在 第 268-283 行 的to_dict中可以看到serializeTrue时输出maxExpirationSeconds、nodeName、stubPKCS10Request等 wire 名键这正与 Kubernetes API server 期望的 JSON 载荷一致因此序列化后的 dict 可直接作为请求 body 发送。实战构造 Spec 并创建 PodCertificateRequest以下示例演示如何用同步客户端构造一个合法的V1beta1PodCertificateRequestSpec并通过CertificatesV1beta1Api.create_namespaced_pod_certificate_request提交aio 异步版 API 定义见 kubernetes/aio/client/api/certificates_v1beta1_api.py同步版位于 kubernetes/client/api/certificates_v1beta1_api.py 对应位置import base64 from kubernetes import client, config config.load_kube_config() # 1. 构造 spec8 个必填字段 spec client.V1beta1PodCertificateRequestSpec( signer_namekubernetes.io/kube-apiserver-client-pod, pod_namemy-app-xxxxx, pod_uid1a2b3c4d-...., service_account_namemy-app-sa, service_account_uide5f6g7h8-...., node_nameworker-01, node_uidi9j0k1l2-...., # kubelet 生成 DER 序列化的 PKCS#10 CSR 后做 Base64 编码 stub_pkcs10_requestbase64.b64encode(csr_der_bytes), # 可选请求最长 24 小时86400 秒也是省略时的默认值 max_expiration_seconds86400, # 可选带域名前缀的扩展元数据 unverified_user_annotations{ example.com/purpose: pod-identity, }, ) # 2. 构造完整的 PodCertificateRequest 对象 req client.V1beta1PodCertificateRequest( api_versioncertificates.k8s.io/v1beta1, kindPodCertificateRequest, metadataclient.V1ObjectMeta(namemy-pod-cert-req), specspec, ) # 3. 提交请求body 支持 dict 或模型对象 api client.CertificatesV1beta1Api() created api.create_namespaced_pod_certificate_request( namespacedefault, bodyreq, )提交时可选参数与 async 版签名一致包括prettytrue时输出美化打印dry_run值为All时执行全部 dry-run 阶段但不持久化field_manager关联的变更者名称小于 128 字符、仅可打印字符field_validationIgnore/Warnv1.23 默认/Strict控制对未知或重复字段的处理方式。创建成功返回V1beta1PodCertificateRequest其中status由签名器通过/status子资源填充。API 层还提供delete_namespaced_pod_certificate_request、list_namespaced_pod_certificate_request、read_namespaced_pod_certificate_request、patch_namespaced_pod_certificate_request及对应的*_status变体见 kubernetes/aio/client/api/certificates_v1beta1_api.py覆盖证书请求资源的完整生命周期。验证性使用from_dict / to_dict 往返由于模型兼容驼峰与下划线两种键从 API 返回的 JSON 反序列化同样简单import json from kubernetes.client.models import V1beta1PodCertificateRequestSpec raw json.loads(created_json_text) # 例如从 read 接口得到的 body spec_obj V1beta1PodCertificateRequestSpec.from_dict(raw[spec]) assert spec_obj.pod_name my-app-xxxxx assert spec_obj.signer_name.startswith(kubernetes.io/) back spec_obj.to_dict(serializeTrue) # back 的键均为 wire 名signerName、podName、stubPKCS10Request ...状态侧补充签名器如何应答理解 Spec 不能脱离其应答方。V1beta1PodCertificateRequestStatus见 kubernetes/aio/client/models/v1beta1_pod_certificate_request_status.py由签名器通过/status子资源填充包含certificateChain一个或多个 PEM 格式证书、conditionsList[V1Condition]及beginRefreshAt、notAfter、notBefore等时间字段。其中conditions的Issued、Denied、Failed三种类型有特殊处理三者至多一个存在且必须为statusTrue。若请求因ReasonUnsupportedKeyType被拒绝签名器可在message中建议可用的密钥类型。这与 Spec 侧文档互相印证客户端选择密钥类型时若不被签名器支持将收到DeniedUnsupportedKeyType的拒绝条件因此自研签名器场景下应保证 Spec 中提交的密钥类型RSA3072/4096、ECDSA P-256/384/521、ED25519在签名器支持列表内。常见错误与排查要点结合源码校验逻辑构造 Spec 时最易踩的坑必填字段缺失8 个必填字段缺一不可Pydantic 会抛出校验错误未知字段extraforbid会拒绝任何未定义字段如误写nodeUIDsbytes 字段的 Base64 约束pkixPublicKey、proofOfPossession、stubPKCS10Request以字符串传入时必须为合法 Base64互斥约束stubPKCS10Request与pkixPublicKey/proofOfPossession不可同时设置前者设置时后者必须为空生命周期越界maxExpirationSeconds小于 3600 会被 kube-apiserver 拒绝大于 7862400 超出允许上限不可变性Spec 所有字段创建后不可变修改需新建请求资源。相关资源索引继续深入可查阅以下仓库文件模型源码同步/异步kubernetes/client/models/v1beta1_pod_certificate_request_spec.py、kubernetes/aio/client/models/v1beta1_pod_certificate_request_spec.py父模型与状态模型kubernetes/aio/client/models/v1beta1_pod_certificate_request.py、kubernetes/aio/client/models/v1beta1_pod_certificate_request_status.pyAPI 客户端kubernetes/aio/client/api/certificates_v1beta1_api.pycreate_namespaced_pod_certificate_request等全部 CRUD 方法OpenAPI 原始定义scripts/swagger.json中v1beta1.PodCertificateRequestSpec定义自动生成文档源doc/source/kubernetes.aio.client.models.v1beta1_pod_certificate_request_spec.rst适用前提说明上述字段语义与校验规则以当前仓库对应的 Kubernetes release-1.37 OpenAPI 文档为准PodCertificateRequest资源处于演进阶段不同集群版本的行为如kubernetes.io/kube-apiserver-client-pod签名器的实现状态可能不同使用前请以目标集群的 API 能力为准。赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 客户端 V1beta1PodCertificateRequest 模型解析Pod 证书请求 API 的字段、校验与使用指南Kubernetes Python 客户端 V1beta1PodCertificateRequest 模型解析Pod 证书请求 API 的字段、校验与使用指南后端云原生容器编排Kubernetes Python 客户端详解StorageV1TokenRequest 模型与 ServiceAccount Token 请求实战Kubernetes Python 客户端详解StorageV1TokenRequest 模型与 ServiceAccount Token 请求实战 本篇技术后端云原生容器编排Kubernetes Python 客户端 V1ObjectFieldSelector 模型解析Pod 字段选择器的构造、序列化与实战用法Kubernetes Python 客户端 V1ObjectFieldSelector 模型解析Pod 字段选择器的构造、序列化与实战用法 本文以 Kuber后端云原生容器编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
