跳到主要内容
Kubernetes

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 共两张,根证书由客户端本地信任库提供。把根证书一并下发会增大握手体积,部分客户端还会判定链异常。

内容审核

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