跳到主要内容
Kubernetes

CFCA SSL 证书在 Kubernetes 中的部署、续期与排错实战

问题背景与根因:为什么 CFCA 证书在 K8s 里常出现客户端校验失败

在 Kubernetes 中,TLS 通常在 Ingress Controller 终止,CFCA 签发的证书以 Secret 形式提供给 ingress-nginx 等控制器。CFCA 支持 RSA/ECC 与国密 SM2 双算法,银行、政务、国企项目常要求国密合规;但主流 ingress-nginx 基于 OpenSSL,直接部署 SM2 证书往往不可用,需要国密网关、Tongsuo 版控制器或独立 GMSSL 终止层。RSA/ECC 证书可按标准 Secret 流程部署。

最常见根因不是证书本身,而是证书链不完整:只上传叶子证书 example.com.pem,未拼接 intermediate.pem。浏览器可能通过 AIA 补链,但 curl、Java、小程序、Go 客户端会报 x509 校验失败。其次要排查 Secret 与 Ingress 是否在同一 namespace、Secret 类型是否为 kubernetes.io/tls、证书与私钥是否匹配、控制器缓存是否刷新。有效期规则也要注意:公开信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,CFCA 商业证书常见 365 天或更短,建议提前 30 天续期。

快速判断可执行:kubectl get secret cfca-example-tls -n prod -o yaml 查看 Secret 是否存在;openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 查看服务端实际下发的证书链。若输出中只有一张叶子证书,基本可判定为链不完整。

前置检查与证书文件准备:叶子证书、中间证书、私钥和 fullchain

CFCA 交付文件通常包含叶子证书、中间证书、根证书和私钥。K8s Secret 的 tls.crt 应放 fullchain,即叶子证书在前、中间证书在后;tls.key 放未加密私钥。先核对主题、签发者和有效期:

openssl x509 -in example.com.pem -noout -subject -issuer -dates
cat example.com.pem intermediate.pem > fullchain.pem
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
openssl verify -CAfile root.pem -untrusted intermediate.pem example.com.pem

验证证书与私钥匹配,RSA 可比较模数 MD5,ECC 建议比较公钥 SHA256,避免算法差异导致误判:

openssl x509 -in example.com.pem -noout -modulus | openssl md5
openssl rsa -in example.com.key -noout -modulus | openssl md5
openssl x509 -in example.com.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl sha256
openssl pkey -in example.com.key -pubout -outform der | openssl sha256

注意不要使用加密私钥,否则 ingress-nginx 加载失败;国密 SM2 证书不要直接套用普通 ingress-nginx Secret,应确认控制器是否支持国密 TLS。公开信任证书最长 398 天,Let’s Encrypt 90 天,CFCA 证书到期前 30 天应启动续期。

用 Secret 部署 CFCA 证书:创建、更新与命名空间检查

Secret 必须与 Ingress 同 namespace,类型为 kubernetes.io/tls。推荐用 dry-run 生成 YAML 再 apply,便于重复执行和审计:

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

不要用 kubectl create secret generic 手工 base64,容易漏掉 type 或键名写错。更新证书时同样执行上述命令,覆盖 tls.crt 和 tls.key。若报 error: tls: private key does not match public key,说明证书与私钥不匹配,回到上一节比较公钥哈希。若报 secret cfca-example-tls not found,优先检查 -n 参数是否与 Ingress 一致。Secret 更新后,Ingress Controller 可能仍使用内存中的旧证书,需要确认控制器是否监听 Secret 变化,必要时滚动重启控制器。

Ingress 配置示例:TLS 引用、强制跳转与协议参数

以下示例适用于 ingress-nginx,证书 Secret 名为 cfca-example-tls。ssl-redirect 和 force-ssl-redirect 控制 HTTP 跳转 HTTPS,ssl-protocols 建议只保留 TLSv1.2 与 TLSv1.3:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cfca-demo-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
      secretName: cfca-example-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

执行 kubectl apply -f cfca-ingress.yaml 后,用 kubectl describe ingress cfca-demo-ingress -n prod 检查 TLS 段是否引用了正确 Secret。若集群有多个 IngressClass,必须确认 ingressClassName 与控制器匹配,否则证书不会生效。TLSv1.3 密码套件通常由控制器全局配置控制,不要误以为 ssl-ciphers 注解能覆盖全部 TLSv1.3 套件。

续期更新与方案对比:手工 Secret、cert-manager 与云托管

CFCA 商业证书通常不是 ACME 自动签发,常见做法是到期前替换 Secret 并滚动重启控制器:

kubectl create secret tls cfca-example-tls 
  --cert=fullchain.pem 
  --key=example.com.key 
  -n prod 
  --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx
kubectl rollout status deployment/ingress-nginx-controller -n ingress-nginx
方案 适用场景 续期方式 注意事项
手工 Secret CFCA 商业证书、审计严格 替换 Secret 后滚动重启 易漏 fullchain,需监控到期
cert-manager ACME Let’s Encrypt 等 ACME CA 自动签发续期 Let’s Encrypt 有效期 90 天
cert-manager 外部 issuer 企业 CA 或 CFCA 集成 依赖 issuer 插件与 API 需确认 CA 接口和权限
云托管证书 云负载均衡 Ingress 控制台自动续期 注意证书链和算法兼容

公开信任证书最长 398 天,不能依赖一年一换;Let’s Encrypt 为 90 天。若使用 cert-manager,执行 kubectl get certificate -A 应看到 Ready=True;但 CFCA 商业证书若无对应 issuer,cert-manager 不能凭空自动续期。

常见错误排查:真实报错与定位命令

客户端报 curl: (60) SSL certificate problem: unable to get local issuer certificate、Java 报 PKIX path building failed、Go 报 x509: certificate signed by unknown authority,优先检查 fullchain 是否缺中间证书。执行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null,若只返回一张证书,说明链不完整。

Secret 创建时报 error: tls: private key does not match public key,用公钥哈希比对证书和私钥。访问报 wrong version number 通常是客户端用 HTTPS 访问了 HTTP 端口,或 Ingress 未正确配置 TLS。报 no such host 先查 DNS 与 host 规则。控制器日志可查:

kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=200 | grep -i -E 'ssl|certificate'
kubectl get ingress cfca-demo-ingress -n prod -o yaml
kubectl get secret cfca-example-tls -n prod -o yaml
openssl x509 -in fullchain.pem -noout -subject -issuer -dates

若浏览器正常但小程序、Java、curl 报错,几乎都是链不完整或根证书不在客户端信任库。若续期后仍显示旧证书,检查 Ingress 是否引用新 Secret、控制器是否重启、CDN 或负载均衡是否缓存旧证书。不要只看浏览器锁标志,必须用 openssl 验证链和到期时间。

效果验证:Secret、Ingress、证书链与到期监控

部署后先查资源状态:kubectl get ingress cfca-demo-ingress -n prod、kubectl get secret cfca-example-tls -n prod。再用外部视角验证:

curl -vI https://example.com
openssl s_client -connect example.com:443 -servername example.com -CAfile root.pem </dev/null
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null | openssl x509 -noout -subject -issuer -dates
openssl x509 -in fullchain.pem -noout -checkend 2592000; echo $?

输出中应看到 Verify return code: 0 (ok),Subject 和 Issuer 与 CFCA 签发信息一致,证书链包含中间证书。checkend 2592000 表示检查 30 天内是否到期,返回 0 表示未到期,返回 1 表示即将到期。若使用 cert-manager,执行 kubectl get certificate -A 确认 Ready=True。最后把到期检查接入监控,至少提前 30 天告警;公开信任证书最长 398 天,Let’s Encrypt 90 天,不能按旧习惯一年一续。

常见问题

RSA/ECC 证书可以,按 Secret 加 Ingress 标准流程部署即可。国密 SM2 证书不能直接套普通 ingress-nginx,需要国密网关、Tongsuo 版控制器或独立 GMSSL 终止层,并确认客户端支持国密套件。


fullchain 包含叶子证书和中间证书,服务端下发完整链后,curl、Java、小程序等客户端才能构建到根证书的信任路径。只放叶子证书时浏览器可能靠 AIA 补链,但非浏览器客户端常报 unable to get local issuer certificate。


先确认 Ingress 引用的 Secret 名称和 namespace 正确,再检查 Ingress Controller 是否监听 Secret 变化。可执行 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx 滚动重启,并排查 CDN、负载均衡或浏览器缓存。


cert-manager 对 ACME 证书自动化最好,例如 Let’s Encrypt 90 天证书。CFCA 商业证书通常需要替换 Secret,除非企业已配置对应的外部 issuer 或 CA 集成接口,否则不能直接自动续期。[/sg_faq_question]

RSA 可比较证书和私钥的 modulus MD5;ECC 更稳妥的是比较公钥 SHA256。两条命令输出一致即匹配。若创建 Secret 报 tls: private key does not match public key,说明文件配错或私钥被加密。


公开信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,CFCA 商业证书常见 365 天或更短。建议提前 30 天续期,并用 openssl x509 -checkend 2592000 做到期监控,避免只靠人工记忆。

内容审核

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