密码学与证书 / 系统课时
用 Certificate 资源管理证书
用 Certificate 资源管理证书
Certificate 资源把“我要什么证书”变成 Kubernetes 中可持续对账的期望状态。本篇会完成一份可落地的声明,覆盖 DNS 名称、私钥、有效期、续期窗口与目标 Secret,并用状态和证书内容验证签发结果。
学习目标
- 能为服务声明 SAN、私钥算法、证书有效期和续期窗口
- 理解
Certificate、签发器与目标Secret之间的职责边界 - 能用
kubectl和openssl验证证书已签发并进入自动续期管理
声明证书期望状态
下面假设命名空间 ingress-system 已存在,并已经准备好名为 public-acme 的 ClusterIssuer。dnsNames 会进入证书 SAN;secretName 是最终交付给工作负载的稳定 Secret 名称。
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: api-example-com
namespace: ingress-system
spec:
secretName: api-example-com-tls
issuerRef:
name: public-acme
kind: ClusterIssuer
dnsNames:
- api.example.com
- alt-api.example.com
privateKey:
algorithm: ECDSA
size: 256
rotationPolicy: Always
duration: 2160h
renewBefore: 360hduration: 2160h 表示请求约 90 天有效期,renewBefore: 360h 表示在剩余约 15 天时进入续期窗口。最终有效期仍受 CA 或签发器策略约束,因此不要把 duration 当成强制承诺。
rotationPolicy: Always 要求重新签发时生成新的私钥。这样证书与私钥会一起轮换,但消费者仍引用同一个 secretName,无需追踪每次签发产生的新证书对象。
看懂控制器如何完成签发与续期
cert-manager 控制器持续观察 Certificate。当目标 Secret 不存在、证书不符合声明,或到达续期时间时,它会创建签发请求并调用 issuerRef 指定的签发器;签发成功后,把 tls.crt 与 tls.key 写入目标 Secret,再继续等待下一次续期窗口。

这套机制的关键是把“证书身份”和“证书内容”分开:Certificate 是长期存在的声明,Secret 中的证书和私钥才是会随续期被更新的交付物。应用、Ingress 或 Gateway 应尽量只绑定稳定的 Secret 名称。
应用并验证签发结果
保存为 certificate.yaml 后执行:
kubectl apply -f certificate.yaml
kubectl -n ingress-system wait \
--for=condition=Ready certificate/api-example-com \
--timeout=120s
kubectl -n ingress-system get certificate api-example-com \
-o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}{.status.notAfter}{"\n"}{.status.renewalTime}{"\n"}'预期输出
certificate.cert-manager.io/api-example-com created
certificate.cert-manager.io/api-example-com condition met
True
<TIME>
<TIME><TIME> 会随签发时间和 CA 策略变化。若超时,不要只反复执行 apply,应先查看 Certificate 与相关 CertificateRequest 的条件和事件。
再检查真正交付给消费者的 Secret:
kubectl -n ingress-system get secret api-example-com-tls \
-o jsonpath='{.type}{"\n"}'
kubectl -n ingress-system get secret api-example-com-tls \
-o jsonpath='{.data.tls\.crt}' \
| base64 -d \
| openssl x509 -noout -ext subjectAltName -dates预期输出
kubernetes.io/tls
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
DNS:api.example.com, DNS:alt-api.example.comOpenSSL 的字段顺序和缩进可能因版本不同而略有差异,但 SAN 必须包含声明的 DNS 名称,且 notAfter 应晚于当前时间。
处理边界与失败
如果 Ready=False,优先检查 kubectl describe certificate 的 Events,再检查签发器是否 Ready、DNS/ACME 校验是否成功以及命名空间权限。renewBefore 必须明显小于 duration,否则可能形成过于频繁的重新签发。
不要让其他控制器或脚本同时写同一个 TLS Secret,也不要通过手工替换 tls.crt 来“续期”。正确做法是修改 Certificate 的期望状态或修复签发链路,让 cert-manager 重新对账;这样 Secret、状态和后续自动续期才能保持一致。