跳到主要内容
Kubernetes

DigiCert SSL 证书部署到 Kubernetes 完整教程:Secret、Ingress 配置与自动续期

问题背景与根因:为什么证书在 K8s 里总是“装了不生效”

在 Kubernetes 中部署 DigiCert 证书,和传统“把 .crt/.key 传到服务器 /etc/nginx/ssl 再执行 nginx -s reload”完全不是一回事:证书是一个 kubernetes.io/tls 类型的 Secret 对象,由 Ingress Controller(nginx-ingress、Traefik、AWS Load Balancer Controller 等)在启动或监听到变更时读入内存,用于 TLS 握手。理解这条链路,才能解释为什么绝大多数“证书明明装了却不生效”的问题都发生在 Secret 与 Controller 的衔接处。

归纳下来有四个高频根因:

  • 证书链不完整。DigiCert 在 CertCentral 上提供的下载包里,服务器证书和中间证书是分开的两个文件。只把叶子证书放进 Secret,Chrome 会因为 AIA 自动补链而显示正常,但 curl、Java、Go、微信小程序这类严格校验的客户端会直接报错。
  • Secret 更新但进程未重载。用 kubectl delete secret 再 create 会有几百毫秒的空窗期,nginx-ingress 此时回落到 fake certificate;部分老版本 Controller 也不会监听 Secret 变化。
  • host 与 SNI 不匹配。Ingress 的 spec.tls[].hosts 必须与证书 SAN 列表一致,否则 Controller 会回落到默认证书。
  • 有效期管理缺失。公开信任的 SSL/TLS 证书最长有效期已被 CA/Browser Forum 限制为 398 天(2020 年 9 月起生效),Let’s Encrypt 更是只有 90 天。按 SC-081 提案,2026-03-15 起将缩短到 200 天、2027 年 100 天、2029 年 47 天,纯手工续期在 K8s 多命名空间场景下基本不可维护。

DigiCert 本身是高端商业 CA,EV 审核与 CertCentral 的批量/API 管理是其优势,银行、证券、大型电商常用;代价是单价高、流程重。因此本教程除了手动 Secret 方案,也会给出 cert-manager 自动化路径,避免每 398 天做一次人工运维。

准备证书文件:从 CertCentral 下载到合并 fullchain

先在 CertCentral 的订单详情页下载证书。格式选择 Apache/Nginx,会得到两个文件:example.com.crt(服务器/叶子证书)与 DigiCertCA.crt(中间证书)。如果下载到的是 .pfx 或 .p7b,需要先转换,K8s 只认 PEM。

# PFX 转 PEM(会输出证书、私钥、链)
openssl pkcs12 -in example.com.pfx -nodes -out all.pem
openssl x509 -in all.pem -out example.com.crt
openssl rsa  -in all.pem -out example.com.key

# 合并完整链:叶子在前,中间在后,不要放根证书
cat example.com.crt DigiCertCA.crt > fullchain.pem

合并顺序错了(中间证书在前)同样会握手失败,务必确认第一段是 subject=CN = example.com 的那张。

校验三件事:链是否完整、私钥是否配对、格式是否可解析。

# 1. 链校验
openssl verify -untrusted DigiCertCA.crt 
  -CAfile DigiCert_Global_Root_G2.crt fullchain.pem
# 期望输出:fullchain.pem: OK

# 2. 打印链中所有证书的主题
openssl crl2pkcs7 -nocrl -certfile fullchain.pem 
  | openssl pkcs7 -print_certs -noout

# 3. 私钥与证书模数比对(RSA)
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in example.com.key | openssl md5
# 两行 MD5 必须完全一致

如果是 ECDSA 证书,没有 modulus,改用公钥比对:openssl x509 -pubkey -noout -in fullchain.pem | openssl md5 与 openssl pkey -pubout -in example.com.key | openssl md5。

私钥格式方面,-----BEGIN PRIVATE KEY-----(PKCS#8)与 -----BEGIN RSA PRIVATE KEY-----(PKCS#1)K8s 都能接受,但必须是未加密的 PEM;带 Proc-Type: 4,ENCRYPTED 的旧格式会导致 Secret 创建失败。转换命令:

openssl pkcs8 -topk8 -nocrypt -in example.com.key -out example.com.pk8.key
chmod 600 example.com.key

最后确认有效期与 SAN,避免域名漏配:openssl x509 -in fullchain.pem -noout -dates -ext subjectAltName。DigiCert 单域名证书只含一个 SAN,多域名/SAN 证书需在下单时就确定好列表,事后无法追加。

创建 TLS Secret:命令行、YAML 与幂等滚动更新

K8s 的 TLS Secret 只有两个必填键:tls.crt(完整链)与 tls.key。Secret 必须与引用它的 Ingress 处于同一 namespace,这是新手最容易忽略的一点。

kubectl create secret tls example-com-tls 
  --cert=fullchain.pem 
  --key=example.com.key 
  -n prod 
  --dry-run=client -o yaml > example-com-tls.yaml

kubectl apply -f example-com-tls.yaml

用 --dry-run=client -o yaml 生成声明式 YAML 而不是直接 create,好处是后续续期可以幂等覆盖,不会出现 delete/create 的空窗。日常续期一条命令即可:

kubectl create secret tls example-com-tls 
  --cert=fullchain.pem --key=example.com.key -n prod 
  --dry-run=client -o yaml | kubectl apply -f -

验证 Secret 内容是否正确(很多问题在这一步就能发现):

# 看证书主体、签发者、到期时间
kubectl get secret example-com-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | openssl x509 -noout -subject -issuer -dates

# 数一下链里有几张证书,正常应 >= 2
kubectl get secret example-com-tls -n prod -o jsonpath='{.data.tls.crt}' 
  | base64 -d | grep -c 'BEGIN CERTIFICATE'

如果偏好纯 YAML 管理(比如配合 GitOps),把文件 base64 后写入:

apiVersion: v1
kind: Secret
metadata:
  name: example-com-tls
  namespace: prod
type: kubernetes.io/tls
data:
  tls.crt: <base64 编码的 fullchain.pem>
  tls.key: <base64 编码的 example.com.key>

注意 Secret 单对象上限 1 MiB,正常证书链远小于此。另外不要把私钥提交到 Git 仓库,配合 SealedSecrets、External Secrets Operator 或 SOPS 使用。生产环境建议同时准备一个 default-ssl-certificate,防止某个 Ingress 漏配 tls 时直接返回 443 握手失败。

Ingress 配置示例:nginx-ingress 与 Traefik 的差异

Secret 建好后,Ingress 通过 spec.tls[].secretName 引用它。下面是一个可直接执行的 nginx-ingress 完整示例:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: prod
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"
    nginx.ingress.kubernetes.io/ssl-ciphers: "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - example.com
        - www.example.com
      secretName: example-com-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80
    - host: www.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

几个关键点:

  • spec.tls[].hosts 里列出的每个域名都必须出现在证书 SAN 中,否则 nginx 会用默认证书兜底,浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID。一张 DigiCert 多域名/SAN 证书可以同时覆盖 example.com 与 www.example.com,共用一个 Secret。
  • force-ssl-redirect 在 TLS 终止于 Ingress 时比 ssl-redirect 更可靠,能避免后端返回 200 时又被降级。
  • 如果 controller 以 --default-ssl-certificate=prod/example-com-tls 启动,未配 tls 的 Ingress 也会使用这张证书,可作为兜底。

Traefik 的写法基本一致,同样在 spec.tls.secretName 引用,但需要确保启动参数开启 --providers.kubernetesingress,并注意 Traefik v2 默认只加载同 namespace 的 Secret;跨 namespace 需配置 --providers.kubernetesingress.allowcrossnamespace=true。

应用后检查是否被 controller 正确接收:

kubectl apply -f ingress.yaml
kubectl describe ingress example-ingress -n prod | grep -A3 TLS
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=50 | grep -i "ssl|secret"

若日志出现 unexpected error validating ingress: secret "example-com-tls" not found,基本可以断定 namespace 写错或 Secret 名拼错。

自动化续期方案对比与 cert-manager 配置

手动 Secret 只能撑到下一次续期。生产集群应优先考虑自动化,四条路线对比如下:

方案 签发/续期方式 续期周期 适用场景 运维成本
手动 Secret + DigiCert CertCentral 下载后 apply 人工,上限 398 天 证书数量少、合规指定 CA 高,易漏期
cert-manager + ACME(Let’s Encrypt/ZeroSSL) 全自动 90 天自动 互联网业务、测试环境 低
cert-manager + Venafi Issuer(DigiCert TLM) 全自动,走企业 CA 按订单,renewBefore 驱动 金融/政企,必须用商业 CA 中,需对接 TLM
External Secrets Operator + CertCentral API 半自动,Secret 同步 由外部 PKI 系统驱动 已有统一 PKI 平台 中

cert-manager 安装(v1.16.x):

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
kubectl get pods -n cert-manager

对接 DigiCert 商业证书走 Venafi Issuer(DigiCert 已收购 Venafi,Trust Lifecycle Manager 提供 TPP 接口):

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: digicert-issuer
  namespace: prod
spec:
  venafi:
    zone: "\\VED\\Policy\\Kubernetes\\example-com"
    tpp:
      url: https://tlm.example.com/vedsdk
      credentialsRef:
        name: venafi-credentials
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
  namespace: prod
spec:
  secretName: example-com-tls
  duration: 8760h      # 申请一年,实际签发受 398 天上限约束
  renewBefore: 720h    # 到期前 30 天自动续期
  commonName: example.com
  dnsNames:
    - example.com
    - www.example.com
  privateKey:
    algorithm: RSA
    size: 2048
  issuerRef:
    name: digicert-issuer
    kind: Issuer

证书状态查询:kubectl get certificate -n prod,READY 列应为 True;异常时 kubectl describe certificate example-com -n prod 会给出 Reason: Failed 与具体错误。cert-manager 会把签发的 fullchain 自动写入 tls.crt,无需再手工合并。

常见错误排查:真实报错与对应修复

下面这些报错在 K8s + DigiCert 场景中出现频率最高,按“现象—根因—修复”列出。

报错信息 根因 修复
curl: (60) SSL certificate problem: unable to get local issuer certificate Secret 里只放了叶子证书,缺中间证书 用 fullchain.pem 重建 Secret
x509: certificate signed by unknown authority 同上,或客户端信任库缺 DigiCert Global Root G2 补链;老旧系统手动导入根证书
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target Java 客户端不做 AIA 补链,链不完整即失败 openssl s_client -showcerts 确认返回 ≥2 张证书
error: failed to load key pair: tls: failed to find any PEM data in certificate input 传入了 DER/P7B 或带密码的私钥 用 openssl 转为未加密 PEM
SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) 证书与私钥不配对 比对 modulus MD5 或公钥指纹
x509: certificate has expired or is not yet valid 证书过期,或节点时间漂移 检查 date 输出并配置 NTP/chrony
secret "example-com-tls" not found Ingress 与 Secret 不在同一 namespace 统一 namespace 或迁移 Secret

最有效的定位命令是直接看服务端实际下发的链:

echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null 
  | openssl x509 -noout -issuer -subject -dates

“浏览器正常但 curl/Java/小程序报错”几乎 100% 是链不完整:Chrome 会通过证书里的 AIA 字段自动下载中间证书补齐,而 curl(OpenSSL)、Java KeyStore、Go 的 crypto/tls 都不会。另一个常见情况是续期后新证书已 apply,但客户端仍拿到旧证书——先确认 Ingress Controller 是否 reload(nginx-ingress 会 watch Secret 自动 reload,老版本需 kubectl rollout restart deploy -n ingress-nginx ingress-nginx-controller),再排查前置 CDN/SLB 的证书是否同步更新。

效果验证:三层校验与到期监控

部署完成后至少做三层验证:集群内 Secret 内容、外部 TLS 握手、持续监控告警。

# 1. 外部握手看到的证书
# 期望 subject 为 example.com,issuer 为 DigiCert 相关 CA
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates

# 2. 链深度,期望 >= 2
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'

# 3. curl 完整校验,期望出现 SSL certificate verify ok.
curl -vI https://example.com 2>&1 | grep -E 'SSL certificate verify|subject:|issuer:|expire date'

# 4. 集群内验证,排除本地 DNS/代理干扰
kubectl run curl-test --rm -it --image=curlimages/curl -n prod -- 
  curl -sSI https://example.com | head -1

再验证强制跳转与协议版本:

# 期望 301/308 且 Location 指向 https
curl -sSI http://example.com | head -3

# 期望被拒绝(仅允许 TLSv1.2/1.3)
openssl s_client -connect example.com:443 -tls1_1 </dev/null 2>&1 | grep -i "alert|error"

最后落到监控。用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标配一条告警,比任何人工台账都可靠:

- alert: SSLCertExpiringSoon
  expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
  for: 1h
  labels:
    severity: warning
  annotations:
    summary: "{{ $labels.instance }} 证书将在 21 天内过期"

如果使用 cert-manager,额外检查 kubectl get certificate -A 的 READY 与 RENEWAL-TIME 列,并为 certmanager_certificate_expiration_timestamp_seconds 建立同等级别的告警。手工 Secret 方案则建议每周执行一次 kubectl get secret -A -o json 加脚本解析到期时间,至少在剩余 30 天时触发工单。

常见问题

公开信任 SSL/TLS 证书上限为 398 天(2020 年 9 月起生效),Let’s Encrypt 为 90 天。CA/B Forum SC-081 计划 2026-03-15 起降至 200 天、2027 年 100 天、2029 年 47 天,因此建议直接采用 cert-manager 自动续期而非手工替换 Secret。

必须。tls.crt 应为“服务器证书 + 中间证书”的 fullchain,叶子证书在前、中间证书在后,不要放根证书。只放叶子证书时浏览器会通过 AIA 自动补链显示正常,但 curl、Java、Go、小程序会报 unable to get local issuer certificate。

新版 nginx-ingress 会 watch Secret 变更并自动 reload,通常无需重启。若使用旧版本、静态证书文件或前置 CDN/SLB,需执行 kubectl rollout restart deploy -n ingress-nginx ingress-nginx-controller,并同步刷新 CDN 上的证书配置。

RSA 证书分别计算模数 MD5:openssl x509 -noout -modulus -in fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5,两值一致才匹配。ECDSA 证书改用公钥比对:openssl x509 -pubkey -noout 与 openssl pkey -pubout。

不能。一个 kubernetes.io/tls Secret 只对应一组 tls.crt/tls.key。多域名应使用 DigiCert 的 SAN/多域名证书合并到一张证书中,或在 Ingress 里为不同 host 配置多个 tls 条目并引用不同 Secret。

可以。通过 Venafi Issuer 对接 DigiCert Trust Lifecycle Manager(TPP 接口)即可全自动签发与续期,也可用 CertCentral API 自建 CronJob 同步 Secret。注意 ACME 协议只适用于 Let’s Encrypt、ZeroSSL 等,普通 CertCentral 订单不走 ACME。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。