用 cert-manager 自动签发和续期证书

适用场景

Kubernetes 中的 Ingress、Gateway 和内部服务需要大量 TLS 证书，手工申请和续期容易过期。cert-manager 可以从 Let's Encrypt、内部 CA 或 Vault 自动签发证书。

前置条件

• Kubernetes 集群和 kubectl。
• 域名 DNS 管理权限，或 80/443 端口可达。
• 选择 ACME 挑战方式：HTTP-01 适合公网 Ingress，DNS-01 适合泛域名和内部服务。
• 内部 CA 场景准备 CA 证书和私钥。

步骤

1. 安装 cert-manager：

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml
kubectl -n cert-manager rollout status deploy/cert-manager
kubectl -n cert-manager rollout status deploy/cert-manager-webhook

2. 创建 ACME ClusterIssuer（HTTP-01）：

kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

3. 泛域名或内网域名使用 DNS-01。以 Route53 为例，使用 IRSA 或 Access Key Secret：

kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-dns-account
    solvers:
    - dns01:
        route53:
          region: ap-east-1
EOF

4. 在 Ingress 上引用 issuer：

kubectl annotate ingress demo \
  cert-manager.io/cluster-issuer=letsencrypt-prod

5. 或直接创建 Certificate 资源，便于非 Ingress 场景使用：

kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: demo-tls
  namespace: demo
spec:
  secretName: demo-tls
  dnsNames:
  - demo.example.com
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
EOF

验证

• kubectl get certificate -A 显示 READY=True。
• kubectl describe certificate demo-tls 中签发和续期时间正确。
• kubectl get challenges,orders 没有长期 Pending。
• 浏览器或 openssl s_client 看到的证书链完整。
• 到期前 30 天自动续期，Secret 中的证书更新。

回滚

• 删除 Certificate 和对应的 Ingress 注解，保留旧证书 Secret。
• 切换 issuer 时先创建新 Certificate，验证后再替换 Ingress 引用。
• 升级 cert-manager 前备份 CRD 和现有 Certificate/Issuer 资源。
• DNS-01 凭据变更时保留旧凭据直到新挑战验证通过。

常见坑

• Ingress class 和 solver 的 ingress.class 不一致，HTTP-01 一直 Pending。
• DNS-01 的 TXT 记录没有传播，挑战超时；检查权威 DNS 和 TTL。
• Let's Encrypt 生产环境有速率限制，调试阶段先用 staging。
• 泛域名只能使用 DNS-01，HTTP-01 不支持。
• 证书 Secret 被手工修改，cert-manager 不会按预期续期。
• 集群出口被防火墙限制，无法访问 ACME 端点。
• 多个 Ingress 共用同一域名但配置不同，证书签发冲突。

相关命令

• cert-manager — 控制器与 webhook
• kubectl — 查看 Certificate、Order、Challenge
• cmctl — 检查证书状态和手动续期
• openssl — 验证证书链和有效期
• dig — 检查 DNS-01 TXT 记录