TrustAsia(亚洲诚信)SSL 证书部署到 Kubernetes 实战:Secret、Ingress 与自动续期
问题背景与根因:为什么“证书装好了”还是报错
在 Kubernetes 里,SSL 证书不是“复制到服务器目录”就完事,它被抽象成 Secret 对象,再由 Ingress 引用。链路上任何一环出错,表现都是“浏览器打不开”或“只有部分客户端报错”。最常见的四类根因如下。
1. 证书链不完整。只上传了叶子证书(example.com.crt),没带中间 CA。桌面浏览器会通过 AIA Fetching 自行补链,所以“我这儿一切正常”;但 curl、Java、微信小程序、部分 Android WebView 不会补链,直接报 unable to get local issuer certificate。TrustAsia 证书通过 DigiCert 授权根签发,必须把“服务器证书 + 中间 CA”拼成 fullchain.pem。
2. Secret 与 Ingress 不在同一 namespace。secretName 只在同命名空间内解析,跨 namespace 引用会静默失败,Ingress Controller 日志报 local SSL certificate default/example-com-tls was not found。
3. 私钥格式错误或密钥对不匹配。重新生成过 CSR、复制时漏了换行或尾随空格,会得到 tls: private key does not match public key。
4. 有效期与缓存。公开 CA 签发的服务器证书最长有效期 398 天(Let’s Encrypt 为 90 天),到期前必须续期;Ingress Controller 对 Secret 有 informer 缓存(nginx-ingress 默认 --sync-period=10m),替换后存在分钟级生效延迟。
理清这四点,后面的操作才有意义:先保证文件正确,再保证 Secret 正确,最后保证引用与生效。
准备与校验证书文件:fullchain 与私钥的三道检查
从 TrustAsia 控制台下载的压缩包通常包含 example.com.crt(服务器证书)、example.com_ca.crt(中间 CA)、example.com.key(私钥)。部署前必须自行拼接 fullchain 并做三道检查。
第一道:拼接并确认链层数。
cat example.com.crt example.com_ca.crt > fullchain.pem
grep -c "BEGIN CERTIFICATE" fullchain.pem # 期望输出 2:叶子证书 + 中间 CA
openssl x509 -in fullchain.pem -noout -subject -issuer -dates
输出中 notAfter 与 notBefore 之差不应超过 398 天;issuer 应是 TrustAsia/DigiCert 的中间 CA 名称,而不是根证书名称。若 grep -c 结果为 1,说明链不完整。
第二道:校验证书与私钥是否配对。两者模数 MD5 必须完全一致:
openssl x509 -in fullchain.pem -noout -modulus | openssl md5
openssl rsa -in example.com.key -noout -modulus | openssl md5
两条输出不同即密钥对不匹配,改配置无用,必须重新签发。ECC 证书改用 openssl ec -in example.com.key -noout -text 比对公钥。
第三道:统一私钥格式。Ingress Controller 走 Go 的 tls.X509KeyPair,PKCS#1(BEGIN RSA PRIVATE KEY)与 PKCS#8(BEGIN PRIVATE KEY)都能读,但部分旧版本组件或云负载均衡只认 PKCS#8,建议统一转换并去掉口令:
openssl pkcs8 -topk8 -nocrypt -in example.com.key -out example.com.pk8.key
chmod 600 example.com.key
openssl x509 -in fullchain.pem -noout -ext subjectAltName
最后确认 SAN 覆盖所有要用的域名——通配符证书只覆盖一级子域,*.example.com 不包含 a.b.example.com。
创建与更新 TLS Secret:三条可执行路径
方式一:命令行创建(最常用)。Secret 必须与 Ingress 同 namespace:
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.key
-n your-namespace
方式二:幂等更新(续期时使用,避免 AlreadyExists)。
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 -
注意 kubectl apply 对 Secret 是整体替换 data 字段,因此必须同时提供 cert 与 key,不能只更新其中一个。
方式三:YAML 清单 + base64(适合 GitOps,密钥建议交给 SealedSecret 或 External Secrets 托管)。
base64 -w0 fullchain.pem > cert.b64
base64 -w0 example.com.key > key.b64
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
name: example-com-tls
namespace: your-namespace
type: kubernetes.io/tls
data:
tls.crt: $(cat cert.b64)
tls.key: $(cat key.b64)
EOF
type 必须是 kubernetes.io/tls,键名必须是 tls.crt / tls.key。写成 cert.pem 之类的自定义键,Ingress 不会识别。
创建后立刻回读校验,确认写入的是 fullchain 而非单证书:
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d | grep -c "BEGIN CERTIFICATE"
输出 1 说明链不完整,必须回到上一步重做。
Ingress 配置示例:引用 Secret 并强制 HTTPS
下面是最小可用且生产可用的 nginx-ingress 配置。注意 tls.hosts 必须与 rules.host 及证书 SAN 三者一致:
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"
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
几个容易踩坑的点:
ingressClassName必须与集群实际安装的 Controller 一致,否则 Ingress 一直处于无地址状态。- 多域名共用一张多 SAN 证书时,
tls.hosts要列全,漏掉的域名会回落默认证书并触发no alternative certificate subject name matches target host name。 - HSTS 一旦下发不可撤销,先在测试域名验证再上生产。
- 若使用 Gateway API,等价写法是
Gateway.spec.listeners[].tls.certificateRefs[].name指向同一 Secret,hostname同样要与 SAN 对齐。
应用后确认 Ingress 已被接管:
kubectl get ingress example-ingress -n your-namespace
kubectl describe ingress example-ingress -n your-namespace | grep -A3 TLS
Events 中出现 Successfully synced 表示配置已下发到 Controller。
续期与滚动更新:手动替换与 cert-manager 自动签发
手动续期流程。证书到期前 30 天从 TrustAsia 控制台重新签发,下载后重做第二、三节的校验,然后执行幂等更新并观察生效:
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 -
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -dates
kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx # 仅在缓存未刷新时使用
若业务 Pod 以 volume 方式挂载了该 Secret(例如应用自己做 TLS 终止),kubelet 的 Secret 同步周期约为 60 秒,但多数进程不会重读文件,需要 kubectl rollout restart 触发重启。
cert-manager 自动签发。适合 DV 场景(含 Let’s Encrypt,有效期 90 天):
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com
namespace: your-namespace
spec:
secretName: example-com-tls
duration: 2160h # 90 天,不可超过 CA 上限 398 天
renewBefore: 720h # 到期前 30 天自动续期
commonName: example.com
dnsNames:
- example.com
- www.example.com
privateKey:
algorithm: RSA
size: 2048
rotationPolicy: Always
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
查看状态:kubectl get certificate -A 应为 READY=True;异常时 kubectl describe certificate example-com -n your-namespace 查看 Events,常见 Waiting for HTTP-01 challenge(域名未解析到 Ingress 或 80 端口不通)。
需要注意:cert-manager 的 ACME Issuer 只签发 DV 证书,无法自动续期从 TrustAsia 购买的 OV/EV 证书,商业证书仍走手动替换流程,或用 External Secrets 从 Vault/KMS 同步。
四种证书交付方式对比
| 方案 | 适用场景 | 续期方式 | 生效延迟 | 主要风险 |
|---|---|---|---|---|
| 手动 kubectl Secret | 小规模、OV/EV 商业证书(TrustAsia 等) | 人工重新签发并 apply | Controller 缓存,最长约 10 分钟 | 忘记续期导致整站证书过期 |
| cert-manager + ACME | 可自动化的 DV 场景 | 按 renewBefore 自动重签 | 分钟级 | ACME 限流、HTTP-01 需公网可达 |
| cert-manager + CA Issuer | 企业内部 CA 签发 | 自动 | 分钟级 | 根证书需分发到所有客户端 |
| External Secrets / Vault | 多集群 GitOps 统一管控 | 由外部 KMS 轮转 | 取决于 refreshInterval | 同步失败无告警,Secret 长期陈旧 |
选型建议:单一集群 + 商业证书用手动 Secret 即可,但必须配到期告警;多集群或域名数量超过 10 个时,优先 cert-manager 或 External Secrets。无论哪种方案,都建议加一条监控:解析 tls.crt 的 notAfter,剩余天数小于 15 天即告警。
常见错误排查:真实报错与对应修复
| 报错原文 | 根因 | 修复动作 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
Secret 里只有叶子证书 | 重新拼接 fullchain,grep -c "BEGIN CERTIFICATE" 应为 2 |
error: failed to load key pair: tls: private key does not match public key |
证书与私钥不是同一对 | 比对 modulus MD5,一致后再创建 |
local SSL certificate your-namespace/example-com-tls was not found |
Secret 与 Ingress 不同 namespace,或名字拼错 | kubectl get secret -n your-namespace 核对 |
PKIX path building failed: unable to find valid certification path to requested target |
Java 客户端不补链 | 同上,补全中间 CA |
x509: certificate has expired or is not yet valid |
证书过期或系统时间偏差 | 续期并检查节点 NTP |
no alternative certificate subject name matches target host name |
访问域名不在证书 SAN 内 | 补 SAN 或调整 Ingress hosts |
排查顺序建议固定下来:先 kubectl describe secret 看是否被正确写入,再 openssl s_client 看服务端实际下发了什么,最后才怀疑客户端。经验上 80% 的问题在第一步——Secret 里存的就是单证书。
另外两个高频现象:一是“续期后不生效”,多为 Ingress Controller 缓存或应用进程未 reload,确认配置指向的是新文件名而非旧路径;二是“只有某个地域访问报错”,检查是否有多套 Ingress Controller 或 CDN 回源使用了另一份旧证书。
效果验证:五条命令确认证书真正生效
不要只看浏览器。按下面顺序逐条执行,每条都有明确预期输出:
# 1. 服务端实际下发的证书主体、签发者、有效期
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# 2. 服务端下发的链层数,应为 2
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c "BEGIN CERTIFICATE"
# 3. 用系统根证书验证链,期望 Verify return code: 0 (ok)
echo | openssl s_client -connect example.com:443 -servername example.com
-CAfile /etc/ssl/certs/ca-certificates.crt 2>/dev/null | grep "Verify return code"
# 4. curl 查看 TLS 握手与证书信息
curl -vI https://example.com 2>&1 | grep -E "SSL certificate|subject:|issuer:|expire"
# 5. 确认 HTTP 已强制跳转 HTTPS
curl -sI http://example.com | head -1 # 期望 HTTP/1.1 301
若 DNS 尚未切换,可用 curl --resolve example.com:443:1.2.3.4 https://example.com -vI 直连指定 IP 验证。
cert-manager 场景额外检查:kubectl get certificate -A 的 READY 列应为 True,kubectl get secret example-com-tls -n your-namespace -o jsonpath='{.metadata.annotations}' 中应能看到 cert-manager.io/certificate-name。最后用 curl -w "%{ssl_verify_result}n" -o /dev/null -s https://example.com 做自动化巡检,返回 0 表示校验通过。
常见问题
公开信任的服务器证书最长有效期为 398 天,TrustAsia 按 CA/B 规范签发,实际以订单为准;Let’s Encrypt 为 90 天。CA/B Forum 已规划逐步缩短至 200/100/47 天,建议用 cert-manager 或到期告警替代人工记日期。
几乎都是链不完整:Secret 里只存了叶子证书。把服务器证书与中间 CA 拼成 fullchain.pem 后重建 Secret,用 grep -c “BEGIN CERTIFICATE” 确认结果为 2,再回读 Secret 验证。
Ingress Controller 对 Secret 使用 informer 缓存,nginx-ingress 默认 –sync-period=10m,所以存在分钟级延迟。可等待一个同步周期,或 kubectl rollout restart 重启 Controller;挂载到业务 Pod 的还需重启应用进程。
可以。使用多 SAN 证书或通配符证书,并在 Ingress 的 tls.hosts 中列全所有域名。注意通配符只覆盖一级子域,且 hosts 漏写会导致该域名回落默认证书并握手失败。
不能。cert-manager 的 ACME Issuer 只签发 DV 证书,无法为外部购买的 OV/EV 证书续期。商业证书需手动替换 Secret,或用 External Secrets 从 Vault、KMS 同步并配合到期监控。
不需要,也不建议。tls.crt 应包含服务器证书加中间 CA 共两张,根证书由客户端本地信任库提供。把根证书一并下发会增大握手体积,部分客户端还会判定链异常。