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。