跳到主要内容
Kubernetes

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。

内容审核

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