Kubernetes 部署 SSL 证书完整指南:Secret、Ingress 与 cert-manager 自动续期
为什么 Kubernetes 里的 SSL 证书总是“装好了却报错”
Kubernetes 不直接读取 PEM 文件,而是通过 Secret(类型 kubernetes.io/tls)把证书交给 Ingress Controller(NGINX Ingress、Traefik、AWS Load Balancer Controller 等),再由控制器渲染成实际的 TLS 配置。这条链路上有四个高频出错点:一是 tls.crt 只放了叶子证书而没放中间证书;二是 Secret 更新了但控制器没重新加载;三是私钥与证书不匹配(常见于重新签发后忘记同步 key);四是证书有效期上限变化——自 2020 年 9 月起,公有 CA 签发的 SSL 证书最长有效期被限制为 398 天,Let’s Encrypt 固定为 90 天,CA/B Forum 已通过 SC-081 决议,2026 年 3 月起逐步压缩到 200 天、100 天、47 天,靠手工续期已经不可持续。
先用一条命令确认线上到底在跑什么证书,避免在错误的 Secret 上反复尝试:
kubectl get secret example-com-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -subject -issuer -dates -serial
再对比客户端实际收到的证书序列号:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -serial -dates
两个 serial 不一致,说明 Secret 与控制器生效配置脱节;一致但客户端仍报 curl: (60) SSL certificate problem: unable to get local issuer certificate,则是证书链不完整。区分这两类根因,后面所有步骤才有意义。
准备证书文件并完成四道本地校验
SSL.com 等商业 CA 签发后通常给到三个文件:example.com.crt(叶子证书)、intermediate.crt(中间证书)、example.com.key(私钥)。Kubernetes 只认一个 tls.crt,因此必须先拼接成 fullchain,叶子证书在前、中间证书在后,顺序颠倒会让部分客户端解析失败:
cat example.com.crt intermediate.crt > fullchain.pem
grep -c "BEGIN CERTIFICATE" fullchain.pem # 期望输出 2(含交叉证书时可能为 3)
openssl x509 -in fullchain.pem -noout -subject -issuer -dates
第二道校验是私钥匹配。RSA 证书比对模数,ECDSA 证书比对公钥,两者不能混用:
# RSA
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
# ECDSA / Ed25519
openssl x509 -in fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in example.com.key -pubout | openssl md5
第三道校验是链验证,确认中间证书能串到受信任根:
openssl verify -untrusted intermediate.crt example.com.crt
# example.com.crt: OK
第四道是域名覆盖检查。商业证书常见 example.com + www.example.com 的 SAN 组合,漏配就会在 www 子域上触发 x509: certificate is valid for example.com, not www.example.com:
openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name"
四项全部通过再进集群,能省掉八成排查时间。私钥文件权限建议 chmod 600 example.com.key,且不要提交进 Git,改用 Sealed Secrets 或 External Secrets Operator 管理。
创建与幂等更新 TLS Secret
首次创建:
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.key
-n prod
注意 --cert 必须指向 fullchain 而非叶子证书,这是最常见的错误来源。Secret 必须与 Ingress 处于同一命名空间,标准 Ingress 不支持跨命名空间引用(Gateway API 的 ReferenceGrant 除外)。
续期时不要 kubectl delete secret,那会造成数秒到数十秒的 TLS 中断。用 --dry-run=client -o yaml | kubectl apply -f - 做原地滚动替换,幂等且不会删除资源:
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/example-com-tls configured
如果后端 mTLS 还需要 CA 证书,可追加 ca.crt 键(类型仍为 kubernetes.io/tls):
kubectl patch secret example-com-tls -n prod --type=merge
-p '{"data":{"ca.crt":"'"$(base64 -w0 root.crt)"'"}}'
还有一个硬限制:etcd 对单个对象默认上限 1 MiB,Secret 的 data 是 base64 编码后的内容,超限会直接报错:
error: failed to create secret Secret "example-com-tls" is invalid:
data[tls.crt]: Too long: may not be more than 1048576 bytes
正常 fullchain(叶子 + 1~2 张中间证书)约 3~6 KB,远不会达到上限;真超限通常是误把整个信任库或 PKCS#12 塞了进去,应剔除根证书、只保留必要中间证书。
Ingress 配置示例:把 Secret 正确挂到域名上
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/proxy-body-size: "16m"
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
要点:tls.hosts 必须与证书 SAN 完全对齐,多写一个未覆盖的域名会让 NGINX Ingress 回退到自签的 Kubernetes Ingress Controller Fake Certificate,浏览器报 NET::ERR_CERT_AUTHORITY_INVALID。spec.ingressClassName 在 1.18+ 取代了 kubernetes.io/ingress.class 注解,两者同时存在可能被不同控制器争抢。
若后端服务自身也跑 HTTPS,需显式声明后端协议,否则 NGINX 会以 HTTP 回源并返回 502:
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/proxy-ssl-secret: "prod/upstream-tls"
不要将 ssl-passthrough 与普通 TLS 终止混用:passthrough 需要控制器启动 --enable-ssl-passthrough,且会绕过 Ingress 的 spec.tls,证书完全由后端 Pod 提供,此时在 Ingress 上改 Secret 不会生效。
用 cert-manager 实现自动签发与续期
在 398 天乃至 90 天的节奏下,手工更新 Secret 必然出错。cert-manager 的标准做法是先定义 Issuer,再定义 Certificate。公共 ACME 证书(Let’s Encrypt,有效期 90 天):
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-key
solvers:
- http01:
ingress:
ingressClassName: nginx
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com-tls
namespace: prod
spec:
secretName: example-com-tls
duration: 2160h # 90 天
renewBefore: 720h # 到期前 30 天开始续期
dnsNames:
- example.com
- www.example.com
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
注意 duration 只是请求值,ACME CA 会强制下发 90 天;对商业 CA(SSL.com 等,上限 398 天)cert-manager 无法自动签发,只能做“自动分发”:用 CronJob 或 External Secrets Operator 把新签发的 fullchain 写入 Secret,再由 Ingress 引用。若使用 cert-manager 的 CA Issuer 自建内部 CA,duration 可自由设置。
验证与排障命令:
kubectl get certificate,certificaterequest,order,challenge -n prod
kubectl describe certificate example-com-tls -n prod
kubectl get events -n prod --field-selector reason=Failed
典型失败原因:Ready=False 且事件为 Waiting for HTTP-01 challenge propagation: failed to perform self check GET request,说明 80 端口被防火墙或 CDN 拦截;Too many certificates already issued for: example.com 则触发了 Let’s Encrypt 每周 50 张同域名限额,调试时应切到 staging 端点。
四种证书管理方案对比
| 方案 | 续期方式 | 适用场景 | 主要风险 |
|---|---|---|---|
手工 kubectl create secret tls |
人工,到期前手动 apply | 少量域名、需人工审核的 EV 证书 | 忘续期;Secret 与本地文件版本不一致 |
| cert-manager + Let’s Encrypt | 全自动,默认在生命周期 2/3 处续期 | 公网 SaaS、开发测试环境 | 90 天短周期;HTTP-01 依赖 80 端口;有速率限制 |
| cert-manager + 商业 CA 同步 | 半自动,CA 签发后由 CronJob/ESO 写入 | 需 OV/EV、走企业采购流程 | 仍需人工在 CA 侧下单与验证 |
| External Secrets Operator 拉取 Vault/ACM | 全自动同步 | 多云、已有密钥管理平台 | 组件依赖多,故障面扩大 |
Secret 内部各键的内容要求也要对齐,否则控制器加载即失败:
| Secret 键 | 正确内容 | 常见错误 |
|---|---|---|
tls.crt |
fullchain:叶子证书 + 中间证书 | 只放叶子证书,导致 unable to get local issuer certificate |
tls.key |
无口令的 PKCS#8 / PKCS#1 私钥 | 私钥带 passphrase,控制器无法解析 |
ca.crt |
可选,中间证书或根证书 | 把根证书混入 tls.crt,徒增体积且部分客户端告警 |
选择建议:公网域名优先 cert-manager + ACME;有合规或品牌要求必须用 OV/EV 时,采用“CA 侧人工签发 + ESO 自动同步 Secret”的组合;单域名临时验证可直接手工创建 Secret,但必须设置到期提醒(如 Prometheus 的 x509-certificate-exporter 监控 cert_expiry_timestamp)。
常见错误排查:六条真实报错与定位命令
1. curl: (60) SSL certificate problem: unable to get local issuer certificate:证书链不完整。执行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null,数一数返回几张证书,只有 1 张即确认缺中间证书。
2. sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target:Java 客户端报错,原因同上,Java 不会像浏览器那样通过 AIA 自动补链。
3. 控制器日志 tls: private key does not match public key:用第 2 节的模数/公钥 MD5 比对定位,重新签发后务必同步替换 cert 与 key。
4. 浏览器 NET::ERR_CERT_AUTHORITY_INVALID 且证书主体为 fake certificate:tls.hosts 里的域名未被证书覆盖,或 Ingress 与 Secret 命名空间不一致。检查:
kubectl describe ingress example-ingress -n prod | grep -A3 TLS
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller | grep -iE "ssl|certificate|secret"
5. 续期后 openssl s_client 仍显示旧序列号:控制器未重新加载。NGINX Ingress 正常会监听 Secret 变化,但自定义镜像或挂载卷模式可能滞后,强制重载:
kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx
kubectl rollout status deploy/ingress-nginx-controller -n ingress-nginx
6. 413 Request Entity Too Large 或无限重定向:前者是 proxy-body-size 默认 1m 导致,按上文注解调大;后者多因 ssl-redirect 与 force-ssl-redirect 同时开启,且前置 CDN 也做了一次 301,形成回源死循环,需在 CDN 侧关闭强制跳转或改用 X-Forwarded-Proto 判断。
效果验证:从 Secret 到客户端四层确认
第一层,确认 Secret 内的证书与本地文件一致:
kubectl get secret example-com-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -serial -dates
openssl x509 -in fullchain.pem -noout -serial -dates
第二层,确认 cert-manager 资源就绪(若使用):
kubectl get certificate -A
# NAMESPACE NAME READY SECRET AGE
# prod example-com-tls True example-com-tls 12d
kubectl describe certificate example-com-tls -n prod | grep -A5 "Events"
第三层,从集群外验证实际握手结果,重点看 issuer、有效期与链长度:
curl -vI https://example.com 2>&1 | grep -E "subject:|issuer:|expire date|SSL certificate verify"
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| openssl x509 -noout -issuer -dates -ext subjectAltName
第四层,验证跳转与 HSTS:curl -sI http://example.com 应返回 301 且 Location: https://example.com/;curl -sI https://example.com | grep -i strict-transport-security 应看到 max-age=31536000。建议再加一条监控告警,把证书剩余天数纳入 Prometheus:剩余不足 21 天即告警,可在 398 天甚至更短的有效期政策下留出充足处置窗口。
常见问题
必须。tls.crt 应是 fullchain,叶子证书在前、中间证书在后。只放叶子证书时桌面浏览器可能靠 AIA 自动补链而显示正常,但 curl、Java、小程序、Go 等客户端没有补链能力,会报 unable to get local issuer certificate。
多为 Secret 与 Ingress 不在同一命名空间,或控制器未重新加载。可执行 kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx 强制重载,再用 openssl s_client 比对序列号确认已切换。
不能。cert-manager 的 ACME 只对接 Let’s Encrypt、ZeroSSL 等 ACME CA,商业 OV/EV 证书需人工完成组织验证后签发。可用 External Secrets Operator 或 CronJob 把新证书自动写入 Secret,实现自动分发。
公有 CA 签发的 SSL 证书当前上限为 398 天,Let’s Encrypt 固定 90 天。按 CA/B Forum SC-081 决议,2026 年 3 月起降至 200 天,2027 年 100 天,2029 年 47 天,应尽早用自动化替代手工续期。
etcd 单对象上限 1 MiB,Secret 以 base64 存储会膨胀约 33%。正常 fullchain 仅几 KB,超限多半是混入了根证书、信任库或 PKCS#12。剔除根证书、只保留叶子加中间证书即可。
RSA 用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 分别取值后比对 MD5;ECDSA 用 -pubkey 与 openssl pkey -pubout 比对。不一致时控制器日志会报 tls: private key does not match public key。