CFCA SSL 证书 Kubernetes 安装部署实战:Ingress、Secret、国密双算法与 398 天续期
问题背景与根因:CFCA 证书上 K8s 为什么常出现“浏览器正常、接口报错”
CFCA(中国金融认证中心)证书常见于银行、政务、国企和国密改造项目,支持国密 SM2 与国际 RSA/ECC 双算法。把证书放进 Kubernetes 的标准做法是创建 tls 类型 Secret,再由 Ingress 的 tls.secretName 引用。实际故障往往不是“证书没买对”,而是部署链路中某一层没有对齐:Secret 在 A 命名空间、Ingress 在 B 命名空间;fullchain 只放了叶子证书;Ingress Controller 仍缓存旧证书;或者把 SM2 证书直接塞进原生 ingress-nginx。公共信任 TLS 证书有效期已缩短为最长 398 天,Let’s Encrypt 为 90 天,旧教程里的 825 天或两年期配置已不适用。排查时先用 openssl x509 -in fullchain.pem -noout -subject -issuer -dates 看主体、签发者和有效期,再用 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 看线上链。根因通常集中在证书链完整性、私钥格式、命名空间与算法兼容性四类;国密场景还要确认客户端是否支持 SM2,以及入口是否使用 Tongsuo/铜锁或国密网关,而不是标准 OpenSSL。先定位失败发生在 Secret、Ingress 还是 TLS 握手层,后面步骤才有意义。
准备证书文件:fullchain、私钥与 SM2/RSA 格式校验
准备文件时至少要有三样:叶子证书、中间 CA 证书、私钥。CFCA 通常交付 .crt 链文件和 .key 私钥,K8s 需要的是 fullchain.pem(叶子在前、中间 CA 在后)和未加密私钥。不要放根证书,根证书应存在于客户端信任库。合并命令:cat example.com.crt cfca_intermediate.crt > fullchain.pem。校验命令:openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName;openssl rsa -in example.com.key -check -noout;openssl x509 -in fullchain.pem -noout -modulus | openssl md5;openssl rsa -in example.com.key -noout -modulus | openssl md5。两个 md5 必须一致。国密证书用 openssl x509 -in sm2.pem -noout -text | grep -i -E ‘SM2|sm2’ 确认算法,私钥用 openssl ec -in sm2.key -noout -text 查看曲线。若私钥带口令,kubectl 不接受,先执行 openssl rsa -in enc.key -out dec.key 去密码;PKCS#8 私钥可转为传统格式:openssl rsa -in key.pem -traditional -out key.rsa。最后用 openssl verify -CAfile cfca_root.pem -untrusted cfca_intermediate.pem fullchain.pem 验证链,返回 OK 再进入 Secret 创建。文件命名建议固定为 fullchain.pem 和 example.com.key,避免脚本引用错文件。
创建 TLS Secret:kubectl 命令与 dry-run 滚动更新
创建 Secret 的命令必须带命名空间,且 Secret 与 Ingress 要在同一 namespace:kubectl create secret tls cfca-example-tls –cert=fullchain.pem –key=example.com.key -n prod。首次创建可直接执行;更新时不要先 delete,否则 Ingress 会短暂无证书。推荐 dry-run 管道滚动替换:kubectl create secret tls cfca-example-tls –cert=fullchain.pem –key=example.com.key -n prod –dry-run=client -o yaml | kubectl apply -f -。若要走 GitOps,可先导出 YAML:kubectl create secret tls cfca-example-tls –cert=fullchain.pem –key=example.com.key -n prod –dry-run=client -o yaml > cfca-secret.yaml,再 kubectl apply -f cfca-secret.yaml。检查类型和字段:kubectl describe secret cfca-example-tls -n prod 应看到 Type: kubernetes.io/tls,Data 包含 tls.crt 与 tls.key。tls.crt 必须是 fullchain,tls.key 必须是未加密私钥;不要用 generic Secret 手工 base64 拼字段,容易把换行和链顺序弄错。若报 error: failed to load key pair: tls: private key does not match public key,回到上一节对比 modulus md5。Secret 更新后同名 Ingress 不需要改 YAML,但入口控制器需要 reload 才会加载新证书,验证时以线上序列号为准。
Ingress 配置示例:host、secretName、ssl-redirect 与多域名
标准 Ingress 配置如下,关键是 ingressClassName、tls.hosts 与 secretName 三者对齐:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cfca-example-ingress
namespace: prod
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: 'true'
nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
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 ingress.yaml,再用 kubectl describe ingress cfca-example-ingress -n prod 查看 TLS 段和 Events。多域名时 tls.hosts 写全,证书 SAN 必须覆盖每个域名;通配符证书用 *.example.com,但只能覆盖一级子域。注意 ssl-redirect 只负责 HTTP 跳 HTTPS,不负责证书链;force-ssl-redirect 在部分版本与 ssl-redirect 同时使用时要确认入口控制器版本支持。国密 SM2 不要直接套用这份配置:原生 ingress-nginx 基于标准 OpenSSL,通常不启用 SM2 握手。国密改造应把 ingressClassName 指向 Tongsuo/铜锁控制器,或在前置国密网关终止 TLS,再由网关转发到 K8s。双算法场景建议同一域名准备 RSA/ECC 与 SM2 两套证书,通过不同入口或 SNI 分流,不要在一个 Secret 里混放两套证书,因为 tls.crt 与 tls.key 只能是一对。配置改完先看 describe 的 Events,再进入握手验证。
国密 SM2 与 RSA/ECC 在 Kubernetes 中的对比与选型
CFCA 支持国密 SM2 与国际 RSA/ECC 双算法,但它们在 Kubernetes 中的落地方式不同。选型时不要只看“算法更强”,要看入口控制器、客户端信任链和合规要求。对比表如下:
| 项目 | RSA 2048/4096 | ECC P-256 | 国密 SM2 |
|---|---|---|---|
| 证书与私钥 | fullchain.pem + RSA key | fullchain.pem + EC key | SM2 证书 + SM2 私钥 |
| 原生 ingress-nginx | 支持 | 支持 | 通常不支持,标准 OpenSSL 未启用 SM2 |
| 国密改造要求 | 无需 | 无需 | 需 Tongsuo/铜锁、国密网关或支持 SM2 的负载均衡 |
| 浏览器兼容 | 全兼容 | 现代浏览器兼容 | 需国密浏览器/插件,公共信任链不同 |
| 握手性能 | 较慢,CPU 开销高 | 较快,密钥短 | 签名快,但生态和硬件支持受限 |
| 有效期 | 公共信任最长 398 天 | 最长 398 天 | 按合规与 CA 策略,仍需监控到期 |
| 典型场景 | 通用 Web/API、旧客户端 | 移动端、高并发 API | 金融、政务、国企国密合规 |
表格里最容易被忽略的是有效期:公共信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,CFCA 国际证书同样受 398 天限制;国密证书按合规策略签发,但不能因此忽略到期监控。若业务既要国密合规又要普通浏览器访问,常见做法是国密网关处理 SM2,后端 K8s Ingress 继续用 RSA/ECC;或者用两个入口分别提供 SM2 与国际算法证书,按客户端能力分流。不要把 SM2 证书放进只支持 RSA/ECC 的 Secret 后指望自动兼容,握手阶段就会失败。
续期与滚动更新:398 天有效期下的自动化脚本
公共信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,续期频率比旧教程高得多。CFCA 商业证书续期后序列号会变化,更新 Secret 必须走滚动替换。可直接执行以下脚本:
#!/usr/bin/env bash
set -euo pipefail
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 --timeout=120s
kubectl get secret cfca-example-tls -n prod -o yaml | grep tls.crt
若入口控制器不是 ingress-nginx,把 deployment 名称换成实际的 controller。更新后检查 Secret 内证书序列号:kubectl get secret cfca-example-tls -n prod -o yaml | grep tls.crt 只能看字段,建议导出后解码对比:kubectl get secret cfca-example-tls -n prod -o yaml 保存,再用 base64 -d 解码 tls.crt,执行 openssl x509 -noout -serial -dates。cert-manager 适合 ACME 场景(如 Let’s Encrypt 90 天自动续期),CFCA 商业证书通常由 CA 平台签发,不要硬套 ACME Issuer;可用 CronJob 调用 CA API 下载新证书,再执行上面的 dry-run 管道。续期窗口建议在到期前 30 天完成,金融合规环境提前 45 天走变更流程。更新后不要只看 kubectl get secret,必须看线上握手返回的序列号是否变化。
常见错误排查:证书链、私钥不匹配与 Ingress 缓存
真实报错通常能直接定位层级。curl 报 curl: (60) SSL certificate problem: unable to get local issuer certificate,说明 fullchain 缺中间 CA,浏览器会自动补链,curl/Java/小程序不会;修复是 cat example.com.crt cfca_intermediate.crt > fullchain.pem 后重建 Secret。Java 报 javax.net.ssl.SSLHandshakeException: PKIX path building failed 同理。kubectl create secret tls 报 error: failed to load key pair: tls: private key does not match public key,或 nginx 报 SSL_CTX_use_PrivateKey failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch),说明证书和私钥不是一对,用 openssl x509 -noout -modulus -in fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5 对比。报 x509: certificate has expired or is not yet valid 时检查 openssl x509 -noout -dates 和集群节点时间。微信小程序报 ssl hand shake error 或 600001,优先查链完整性和 TLS 版本,用 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 看返回链。续期后仍返回旧序列号,是 Ingress Controller 缓存或未 reload,执行 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx,并确认 Ingress 引用的 secretName 没有指向旧 Secret。排查顺序:Secret 字段、链顺序、私钥匹配、控制器 reload、客户端信任库。
效果验证:从 Secret 到公网 TLS 握手逐层确认
验证要分层,不要只看浏览器。第一步看 Secret:kubectl describe secret cfca-example-tls -n prod,确认 Type 为 kubernetes.io/tls 且 tls.crt、tls.key 都存在。第二步看 Ingress:kubectl describe ingress cfca-example-ingress -n prod,确认 TLS 段 host 与 secretName 正确、Events 无报错。第三步集群内验证:kubectl run curl-test –image=curlimages/curl -it –rm –restart=Never — curl -vI https://example.com –resolve example.com:443:10.0.0.10,把 IP 换成入口地址,确认 Pod 内解析和握手都正常。第四步公网验证:curl -vI https://example.com;openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates -serial -ext subjectAltName。预期是 SAN 覆盖域名、issuer 为 CFCA 中间 CA、notBefore/notAfter 覆盖当天、serial 与 Secret 内一致。第五步协议验证:openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null,再测 -tls1_3;需要更全面可用 testssl.sh –fast https://example.com。若线上序列号仍旧,等待控制器 reload 或主动 rollout restart。最后用不同客户端各测一次:curl、Java、微信小程序、国密浏览器,分别覆盖严格链校验和 SM2 场景。
常见问题
推荐用 kubernetes.io/tls 类型 Secret,由 Ingress 的 tls.secretName 引用,控制器会自动加载并支持轮换。也可以把证书文件挂载进 Pod,但需要自己 reload 进程,且容易漏掉链文件,不适合标准 Ingress 场景。
fullchain.pem 包含叶子证书和中间 CA,cert.pem 通常只有叶子证书。浏览器可能自动补链,但 curl、Java、微信小程序会严格校验,缺中间 CA 就报 unable to get local issuer certificate。K8s Secret 的 tls.crt 应使用 fullchain。
通常不能。原生 ingress-nginx 基于标准 OpenSSL,默认不启用 SM2 握手。需要 Tongsuo/铜锁控制器、国密网关或支持 SM2 的负载均衡终止 TLS,再把请求转发到 K8s 后端。
先确认 Secret 已用同名 dry-run 管道更新,再执行 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx。用 openssl s_client 查看线上序列号是否变化,并检查 Ingress 的 secretName 是否仍指向旧 Secret。
公共信任 TLS 证书最长有效期为 398 天,CFCA 国际算法证书同样受此限制;Let’s Encrypt 为 90 天。国密证书按合规与 CA 策略签发,但仍需设置到期监控和提前续期窗口。
cert-manager 更适合 ACME(如 Let’s Encrypt 90 天)或内部 CA Issuer。CFCA 商业证书通常由 CA 平台签发,建议用 CronJob 调用 CA API 下载新证书,再通过 kubectl dry-run 管道更新 Secret,不要硬套 ACME Issuer。