TrustAsia SSL 证书部署到 Kubernetes 实战:Secret、Ingress 配置与自动续期
问题背景与根因:Kubernetes 里 TLS 为什么“配了却不生效”
把 TrustAsia(亚洲诚信)签发的证书搬进 Kubernetes,失败点几乎从不在证书本身,而集中在三个环节:Secret 里装的是什么、Ingress 怎么引用、Controller 何时重新加载。TrustAsia 的公共信任证书通过 DigiCert Global Root CA / Global Root G2 签发(含交叉签名链),浏览器与操作系统预置了这些根证书,但中间证书必须由服务端下发。一旦只挂叶子证书(example.com.crt),浏览器可能靠 AIA 自动补链“侥幸正常”,而 curl、Java、微信小程序、Go 客户端会直接报 unknown authority。
第二类根因是有效期与续期节奏。当前公共 TLS 证书最长有效期为 398 天(2020-09-01 起生效),Let’s Encrypt 默认 90 天并已提供 6 天短周期证书选项;CA/Browser Forum 已通过分阶段缩短方案,2026-03-15 起降至 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天。“一年一换、手工上传”的流程在 K8s 里会越来越频繁地撞上过期事故。
第三类是缓存与引用错位:ingress-nginx 把证书缓存在内存中,Secret 更新后需等待 watch 触发 reload(通常 30 秒内),老版本或异常情况下必须手动重启;Secret 又只能被同命名空间的 Ingress 引用,跨 namespace 引用会静默失败,表现为握手仍用默认证书。
先做一次集群体检,列出所有 TLS Secret,再逐条看真实到期时间:
kubectl get secret -A --field-selector type=kubernetes.io/tls
-o custom-columns='NS:.metadata.namespace,NAME:.metadata.name'
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -subject -issuer -enddate
如果第二条命令报 error: error decoding from jsonpath,多半是 shell 把反斜杠吃掉,用单引号包裹 jsonpath 即可。拿到 notAfter 后,把到期日写进值班日历,或交给后文的自动巡检脚本。
第一步:整理证书文件并校验链完整性
TrustAsia 交付的压缩包通常包含:example.com.crt(叶子证书)、ca-bundle.crt 或 chain.crt(中间证书)、example.com.key(私钥)。K8s 的 Secret 只需要两个键:tls.crt 与 tls.key,其中 tls.crt 必须是叶子 + 中间的完整链,且顺序不能反,也不要塞入根证书。
# 1. 合并完整链(叶子在前,中间在后)
cat example.com.crt chain.crt > fullchain.pem
grep -c 'BEGIN CERTIFICATE' fullchain.pem # 期望输出 2
# 2. 用中间证书验证链是否完整
openssl verify -untrusted chain.crt fullchain.pem
# fullchain.pem: OK
# 3. 校验私钥与证书匹配(RSA)
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
# 两行 md5 必须一致
# ECDSA 证书改用公钥比对
openssl x509 -noout -pubkey -in fullchain.pem | openssl md5
openssl pkey -pubout -in example.com.key | openssl md5
# 4. 核对 SAN 与有效期
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
三个高频坑位:其一,私钥不能带口令,kubernetes.io/tls Secret 不支持加密私钥,带 passphrase 的 key 会让 kubectl 直接报 error: failed to load keypair: tls: failed to find any PEM data in key input,先用 openssl rsa -in enc.key -out example.com.key 解密,再 chmod 600 example.com.key;其二,Windows 导出的文件可能带 BOM 或 CRLF,用 file fullchain.pem 确认是 PEM/ASCII text,必要时 dos2unix fullchain.pem;其三,PFX 格式必须先转 PEM:openssl pkcs12 -in cert.pfx -nodes -out all.pem,再从 all.pem 中拆出证书与私钥。
为什么不要放根证书:部分 Java 旧版本与 Android 客户端遇到链中出现自签根会抛 path building 异常,规范做法是只下发叶子 + 中间,根由客户端信任库提供。若链中确实需要交叉签名证书(TrustAsia 某些产品线会附带),顺序应为“叶子 → 中间 → 交叉证书”。
第二步:用 Secret 装载证书(可重复执行的更新方式)
不要把证书写进 ConfigMap 或打进镜像。正确做法是创建 kubernetes.io/tls 类型的 Secret,Ingress 通过 secretName 引用,证书更新只动 Secret,不动业务 Pod。
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.key
-n your-namespace
--dry-run=client -o yaml | kubectl apply -f -
# 首次输出 secret/example-com-tls created,再次执行输出 configured
--dry-run=client -o yaml 配合 kubectl apply 是幂等写法:首次创建、后续覆盖。续期时不要先 kubectl delete secret 再创建,那一瞬间 Ingress 找不到证书,会返回默认自签证书或直接握手失败。
kubectl get secret example-com-tls -n your-namespace
# NAME TYPE DATA AGE
# example-com-tls kubernetes.io/tls 2 10s
DATA 必须是 2(tls.crt 与 tls.key 都在)。若用 generic 方式创建,必须显式声明类型,否则 Ingress 不识别:
kubectl create secret generic example-com-tls
--type=kubernetes.io/tls
--from-file=tls.crt=fullchain.pem
--from-file=tls.key=example.com.key
-n your-namespace
另外两个限制要记住:Secret 单对象上限 1MiB(etcd 默认 1.5MiB),正常链只有几 KB,塞整包 PFX 才会超限;Secret 必须与 Ingress 同 namespace,跨 namespace 引用在 ingress-nginx 日志中表现为 local SSL certificate ns/name was not found。私钥读取权限由 RBAC 控制,可用 kubectl auth can-i get secrets -n your-namespace 判断某个 ServiceAccount 是否能读。
第三步:Ingress 配置示例与 TLS 加固参数
下面是 networking.k8s.io/v1 的完整可用配置,包含 HTTP 强制跳转、协议收敛、HSTS 与多域名共用一张证书的写法。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
namespace: your-namespace
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/hsts: 'true'
nginx.ingress.kubernetes.io/hsts-max-age: '31536000'
nginx.ingress.kubernetes.io/hsts-include-subdomains: 'true'
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 必须与 rules.host 一一对应,否则 SNI 匹配不上会回落到默认证书;ssl-protocols 显式禁用 TLSv1.0/1.1,等保与支付合规通常强制要求;hsts-include-subdomains 对含未启用 HTTPS 子域的业务要谨慎,一旦下发浏览器会长期强制 HTTPS。若需要上传大文件,再补 nginx.ingress.kubernetes.io/proxy-body-size: '50m'。
应用并检查:
kubectl apply -f ingress.yaml
kubectl describe ingress example-ingress -n your-namespace
# TLS:
# example-com-tls terminates example.com,www.example.com
如果集群有多个 Ingress Controller,务必写 ingressClassName,否则资源会被忽略。全局兜底证书可在 Controller 启动参数中配置 --default-ssl-certificate=your-namespace/example-com-tls,用于未匹配域名的 HTTPS 请求。
第四步:续期替换、有效期新规与自动巡检
手工续期后,用同一条幂等命令滚动替换 Secret,ingress-nginx 会自动感知:
kubectl create secret tls example-com-tls
--cert=fullchain.pem --key=example.com.key -n your-namespace
--dry-run=client -o yaml | kubectl apply -f -
# 观察 Controller 是否重载
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=50 | grep -i 'reload|ssl'
# 若 1 分钟后仍是旧证书
kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx
批量巡检所有 TLS Secret 的到期时间,建议做成 CronJob 每天跑一次:
kubectl get secret -A --field-selector type=kubernetes.io/tls
-o custom-columns='NS:.metadata.namespace,NAME:.metadata.name' --no-headers |
while read ns name; do
end=$(kubectl get secret "$name" -n "$ns" -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -enddate | cut -d= -f2)
echo "$ns/$name -> $end"
done
有效期新规必须提前纳入规划,否则流程会被动断裂:
| 生效日期 | 公共 TLS 证书最长有效期 | 运维影响 |
|---|---|---|
| 2020-09-01 起(现行) | 398 天 | 一年一换,手工可维持 |
| 2026-03-15 起 | 200 天 | 约半年一换 |
| 2027-03-15 起 | 100 天 | 季度级,需半自动化 |
| 2029-03-15 起 | 47 天 | 必须全自动,否则必然过期 |
cert-manager 用户可以声明式管理,注意 duration 只是“期望值”,实际有效期由 CA 决定:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com
namespace: your-namespace
spec:
secretName: example-com-tls
duration: 8760h
renewBefore: 720h
issuerRef:
name: trustasia-issuer
kind: ClusterIssuer
dnsNames:
- example.com
- www.example.com
OV/EV 商业证书即使有效期缩短,组织验证仍需人工,建议把“签发 → 校验 → kubectl apply”固化成 CI 流水线,并保留回滚用的旧 Secret 副本。
方案对比:五种 K8s 证书部署方式怎么选
不同规模与合规要求对应不同方案,下表按实际运维成本排序:
| 方案 | 证书来源 | 续期方式 | 优点 | 局限 |
|---|---|---|---|---|
| 手工 Secret + Ingress | TrustAsia DV/OV/EV | 人工替换 Secret | 可控、无外部依赖、支持 OV/EV | 依赖值班,域名多时易漏 |
| cert-manager + ACME | Let’s Encrypt / ZeroSSL | 到期前 30 天自动签发 | 全自动,零人工 | 仅 DV,不支持 OV/EV,90 天周期 |
| cert-manager + 商业 CA issuer | TrustAsia 等 | API 或导入后自动更新 Secret | 兼顾 OV/EV 与自动化 | 需维护 issuer 组件与凭证 |
| 外部负载均衡 / API 网关终止 | 任意 | 在网关侧统一更新 | 证书集中管理,集群内无 Secret | 网关到 Pod 需额外 mTLS 才能端到端加密 |
| Istio Gateway / Service Mesh | 任意 | SDS 动态下发,无需重启 | 热更新、支持双向 TLS | 架构复杂,资源开销大 |
选型建议:域名少于 5 个且需要 OV/EV 品牌展示,手工 Secret 完全够用,但要配上巡检脚本;域名超过 10 个或需要频繁扩缩容,直接上 cert-manager;金融、政务类必须 OV/EV 又要自动化的场景,用 cert-manager 的商业 CA issuer 或自建“签发后自动 apply”的流水线。无论哪种方案,都要保证 tls.crt 是完整链、Secret 与 Ingress 同 namespace、更新过程幂等。
另外,TrustAsia 还提供 SM2 国密证书,这类证书不能直接挂到标准 nginx ingress-nginx 上,需要国密版网关(Tengine + Tongsuo)或支持双证书的负载均衡,规划时要单独评估。
常见错误排查:真实报错与修复命令
1. error: tls: private key does not match public key
证书与私钥不是一对,或 fullchain.pem 的第一段不是该私钥对应的叶子证书。修复:用前文的 modulus / pubkey md5 比对;确认 head -1 fullchain.pem 是 -----BEGIN CERTIFICATE-----,且第一段证书的 SAN 覆盖目标域名。
2. error: failed to load keypair: tls: failed to find any PEM data in certificate input
文件是 DER 或 PFX 格式,或带 BOM、CRLF。修复:openssl x509 -in cert.crt -inform DER -out cert.pem;openssl pkcs12 -in cert.pfx -nodes -out all.pem;dos2unix fullchain.pem。
3. curl: (60) SSL certificate problem: unable to get local issuer certificate
链不完整。Java 侧表现为 PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target,微信小程序表现为 request:fail ssl hand shake error。修复:tls.crt 换成 fullchain,再用 openssl s_client -connect example.com:443 -servername example.com -showcerts 确认服务端返回 2 张证书。
4. ingress-nginx 日志:local SSL certificate your-namespace/example-com-tls was not found
Secret 名拼错或不在同一 namespace。修复:kubectl get secret -n your-namespace | grep tls,核对 Ingress 的 spec.tls[0].secretName。
5. x509: certificate is valid for example.com, not api.example.com
SAN 未覆盖该域名,属于证书本身问题,无法靠 Ingress 配置绕过。修复:重新签发含该域名的多域名或通配符证书;注意通配符 *.example.com 不覆盖 example.com 本身。
6. 续期后浏览器仍显示旧证书
三层缓存:Controller 内存缓存、CDN 边缘缓存、浏览器缓存。依次验证:openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -enddate 看 notAfter 是否为新日期;再 kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx;最后刷新 CDN 证书。
效果验证:从 Secret 到公网的四层检查
部署完成后按四层依次验证,任何一层失败都能快速定位:
# 第 1 层:Secret 内的证书内容
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -subject -issuer -dates
# 第 2 层:Ingress 是否挂载成功
kubectl describe ingress example-ingress -n your-namespace | sed -n '/TLS/,/Rules/p'
# 第 3 层:集群内验证(绕过 DNS 与 CDN)
kubectl run curl-test --rm -it --image=curlimages/curl:8.8.0 --restart=Never --
curl -sI https://example.com --resolve example.com:443:10.0.0.10
# 第 4 层:公网验证,检查链、协议与密码套件
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null
| openssl x509 -noout -issuer -dates
openssl s_client -connect example.com:443 -servername example.com -verify_return_error
</dev/null 2>&1 | grep -E 'Verify return code|Protocol|Cipher'
# Verify return code: 0 (ok) / Protocol: TLSv1.3 / Cipher: TLS_AES_256_GCM_SHA384
补充检查项:curl -sI https://example.com | grep -i strict-transport-security 应看到 max-age=31536000;keytool -printcert -sslserver example.com:443 | head -20 可在 Java 环境确认链与有效期;cert-manager 用户执行 kubectl get certificate -A,READY 列必须为 True,kubectl describe certificate example-com -n your-namespace 可看到 Renewal Time。
最后用外部评级做交叉验证:SSL Labs 目标为 A 及以上,重点看“证书链不完整”“TLS 1.0/1.1 可协商”“未启用 HSTS”三类告警。若评级为 B,通常是协议未收敛,回到 Ingress 的 ssl-protocols 注解修正即可。整套验证建议固化进发布流水线,每次证书替换自动跑一遍。
常见问题
现行公共 TLS 证书最长有效期为 398 天,TrustAsia 的 DV、OV、EV 证书均按此上限签发,Let’s Encrypt 则为 90 天。按 CA/Browser Forum 已通过的方案,2026-03-15 起缩短至 200 天,2027 年 100 天,2029 年 47 天,因此 K8s 环境必须尽早准备自动续期与巡检机制。
必须用完整链。tls.crt 应为“叶子证书 + 中间证书”,顺序不能颠倒,也不要包含根证书。只放叶子证书时,浏览器可能靠 AIA 补链正常显示,但 curl、Java、微信小程序等客户端会报 unable to get local issuer certificate 或 PKIX path building failed。
通常不需要。ingress-nginx 会 watch Secret 变化并在约 30 秒内自动 reload。若用 openssl s_client 检查仍返回旧的 notAfter,再执行 kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx 强制重载,同时排查 CDN 是否缓存了旧证书。
可以,只要证书的 SAN 覆盖全部域名。需在 spec.tls[0].hosts 和 rules.host 中把所有域名列全,SNI 才能正确匹配。注意通配符证书 *.example.com 不覆盖裸域 example.com,除非签发时同时包含两个 SAN。
能,但需要支持该 CA 的 issuer,例如商业 CA 提供的 webhook issuer 或 CA Issuer 导入方式;ACME 协议只适用于 DV 证书。OV/EV 的组织验证仍需人工完成,常见做法是签发后由 CI 流水线执行 kubectl apply 更新 Secret。
因为浏览器会通过证书中的 AIA 字段自动抓取缺失的中间证书,而服务端 HTTP 客户端不会。用 openssl s_client -showcerts 检查服务端是否只返回 1 张证书,若如此,把 tls.crt 换成叶子加中间的完整链即可解决。