跳到主要内容
Kubernetes

SSL.com SSL 证书 Kubernetes 安装部署实战:Secret、Ingress、续期与排错

问题背景与根因

Kubernetes 本身不直接读取证书文件,Ingress 通过 Secret 完成 TLS 终止。把 SSL.com 签发的证书部署到 K8s 时,常见故障不是证书没签发,而是 Secret、Ingress 与 Ingress Controller 三者不一致。典型根因包括:Secret 类型不是 kubernetes.io/tls;Secret 与 Ingress 不在同一命名空间;证书文件误用叶子证书而非 fullchain.pem,导致中间证书缺失;Ingress Controller 未监听 Secret 变化或仍缓存旧证书;续期后只替换了文件但没有更新 Secret。

另一个容易忽略的是有效期规则。公有 TLS 证书需遵循 CA/Browser Forum 要求,单张证书最长有效期 398 天;Let’s Encrypt 采用 90 天短期证书和自动续期模型。旧教程中按 1 年或 2 年规划续期的做法已经过时。部署前先用命令确认证书主题、签发者和到期时间:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout

第二条命令用于查看 fullchain.pem 中是否包含多张证书。生产环境建议把续期检查纳入监控,在到期前 30 天完成更新。对于 SSL.com 商业证书,通常由人工或 CI 流水线把新证书导入 Secret;cert-manager 更适合 ACME 证书或内部 CA 的自动签发续期,不能想当然认为它能直接续期所有商业证书。

证书文件准备与有效期校验

从 SSL.com 下载证书包后,至少保留三个文件:fullchain.pem、example.com.key 和可选的 example.com.csr。fullchain.pem 应包含服务器证书和中间证书,顺序为叶子证书在前、中间证书在后;example.com.key 是签发时生成的私钥。若私钥丢失,只能重新签发或重新生成 CSR。CSR 可用以下命令生成,注意 -subj 中的 CN 必须与域名一致:

openssl req -new -newkey rsa:2048 -nodes -keyout example.com.key -out example.com.csr -subj /CN=example.com
chmod 600 example.com.key

部署前必须做三项校验。第一,检查证书有效期和主题:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates

第二,检查证书与私钥是否匹配。分别计算模数 MD5,两条输出必须一致:

openssl x509 -in fullchain.pem -noout -modulus | openssl md5
openssl rsa -in example.com.key -noout -modulus | openssl md5

第三,检查证书链是否完整。可用 openssl s_client 连接测试域名,观察是否返回中间证书;本地文件可查看 fullchain.pem 中的证书数量。若只有一张叶子证书,Java、小程序和部分 curl 客户端会报证书链错误。不要把 cert.pem 直接当作 fullchain.pem 使用,也不要把私钥提交到 Git。Secret 创建命令会在下一步给出。

完整实操步骤

以下命令以命名空间 your-namespace、Secret 名 example-com-tls、域名 example.com 为例,执行前替换为实际值。第一步创建命名空间,幂等写法如下:

kubectl create namespace your-namespace --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key -n your-namespace

第二步确认 Secret 类型和命名空间。Secret 必须是 kubernetes.io/tls 类型,且与 Ingress 同命名空间:

kubectl get secret example-com-tls -n your-namespace
kubectl describe secret example-com-tls -n your-namespace

第三步部署 Ingress。将下一节的 YAML 保存为 example-ingress.yaml,然后执行:

kubectl apply -f example-ingress.yaml
kubectl get ingress example-ingress -n your-namespace -o wide

第四步处理续期。证书更新后不要只覆盖本地文件,必须更新 Secret。推荐用 dry-run 生成 YAML 后 apply,避免删除 Secret 造成 TLS 中断:

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 rollout restart deployment/ingress-nginx-controller -n ingress-nginx

最后一条重启命令是兜底手段,适用于 Ingress Controller 未自动加载新 Secret 的情况;不同 Controller 的命名空间和 Deployment 名称不同,先确认再执行。若使用 cert-manager 管理 ACME 证书,则用 kubectl get certificate -A 查看 Ready=True,而不是手工创建 Secret。

配置示例

以下 Ingress 使用 networking.k8s.io/v1,TLS 部分引用前面创建的 Secret,并通过 annotation 强制 HTTP 跳转 HTTPS。将 example.com、example-com-tls、web 和 your-namespace 替换为实际值:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: your-namespace
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: 'true'
spec:
  tls:
    - hosts:
        - example.com
      secretName: example-com-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

应用后检查 Ingress 是否拿到地址和 TLS 配置:

kubectl apply -f example-ingress.yaml
kubectl describe ingress example-ingress -n your-namespace

若后端 Service 端口不是 80,需要同步修改 number。若 Ingress Controller 使用默认证书兜底,仍应在 Ingress 中显式声明 tls.secretName,避免域名不匹配。对于 cert-manager 场景,Certificate 资源会生成同名 Secret,Ingress 继续引用 secretName 即可;但 SSL.com 商业证书通常仍以 fullchain.pem 和私钥导入 Secret 为主。配置完成后不要忘记检查 IngressClass 是否匹配,否则 Ingress 不会生效。

部署与续期方案对比表格

不同团队应根据证书来源、域名数量和合规要求选择方案。下表对比 Kubernetes 中常见的四种 TLS 证书落地方式,重点看续期方式和风险点:

方案 适用场景 续期方式 关键命令或资源 风险点
手动 Secret SSL.com 商业证书、少量域名 到期前重新 apply Secret kubectl create secret tls … –dry-run=client -o yaml | kubectl apply -f – 人工遗漏、覆盖 Secret 时短暂不一致
cert-manager ACME Let’s Encrypt 90 天证书或支持 ACME 的 CA 自动续期 Certificate、Issuer、ClusterIssuer 商业证书不一定支持 ACME;DNS-01 配置错误
Controller 默认证书 测试环境或兜底访问 随 Controller 配置更新 –default-ssl-certificate 域名不匹配,生产不可依赖
外部 Secret 管理 多集群、合规审计 流水线或控制器轮换 CI、Kubernetes API、Secrets Store CSI 权限和审计复杂,需防泄露

如果证书来自 SSL.com 且没有 ACME 接口,推荐手动 Secret 加 CI 自动化:流水线在证书到期前 30 天触发更新,执行 dry-run 后 apply,并调用 kubectl rollout restart 或等待 Controller 热加载。域名多、集群多时,应把 Secret 更新纳入发布系统,避免各集群证书版本不一致。不要把商业证书私钥放在 ConfigMap 或镜像层中。

常见错误排查(含真实报错)

排错顺序建议从证书链、私钥匹配、Secret 引用、Controller 加载四层入手。以下报错在 Kubernetes 部署 SSL.com 证书时较常见:

  • 浏览器正常但 curl 报 curl: (60) SSL certificate problem: unable to get local issuer certificate,Java 报 sun.security.validator.ValidatorException: PKIX path building failed。根因是证书链不完整。检查 Secret 是否使用 fullchain.pem,执行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 查看返回证书数量。
  • 创建 Secret 时报 error: failed to load key pair: tls: private key does not match public key。用 openssl x509 -in fullchain.pem -noout -modulus | openssl md5 与 openssl rsa -in example.com.key -noout -modulus | openssl md5 比对,输出不一致说明证书和私钥不是一对。
  • Ingress 日志出现 secret example-com-tls not found。检查 Secret 与 Ingress 是否在同一命名空间,tls.secretName 是否拼写一致,执行 kubectl get secret -n your-namespace。
  • 访问返回 default backend – 404。TLS 可能已生效,但 host 或 path 未匹配;检查 rules.host、pathType 和 Service 端口。
  • 客户端报 x509: certificate signed by unknown authority 或 x509: certificate has expired or is not yet valid。前者仍是链问题,后者检查 openssl x509 -in fullchain.pem -noout -dates,并确认节点时间同步。
  • 续期后仍显示旧证书。确认 Secret 已 apply,Controller 已 reload,CDN 或负载均衡没有缓存;用 openssl s_client 查看 notAfter 是否为新日期。

效果验证

部署完成后从 Kubernetes 对象、TLS 握手和客户端三个层面验证。先看 Secret 和 Ingress 状态:

kubectl get secret example-com-tls -n your-namespace
kubectl get ingress example-ingress -n your-namespace
kubectl describe ingress example-ingress -n your-namespace

再用 curl 检查 HTTP 状态和证书信息。若配置了 ssl-redirect,HTTP 应返回 301 或 308,HTTPS 应返回 200:

curl -vI https://example.com
curl -vI http://example.com

用 openssl s_client 查看服务端实际下发的证书链、主题、签发者和到期时间:

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates

输出中应看到 subject 与域名一致,issuer 为 SSL.com 对应 CA,notAfter 为新有效期。若命令输出 Verify return code: 0 (ok),说明链验证通过;若为 20 或 21,分别检查中间证书和有效期。cert-manager 场景执行 kubectl get certificate -A,确认 Ready=True。最后用浏览器、Java 客户端或小程序真机复测,避免只验证 curl 而漏掉证书链兼容性问题。

常见问题

应存为 kubernetes.io/tls 类型的 Secret,用 kubectl create secret tls 创建,证书填 fullchain.pem,私钥填 example.com.key。Secret 必须与 Ingress 同命名空间,并由 tls.secretName 引用;ConfigMap 不参与 TLS 终止,不能替代 Secret。


优先怀疑证书链不完整。浏览器可能自动补链,Java 和小程序不会。检查 Secret 是否误用叶子证书,改用包含中间证书的 fullchain.pem,并用 openssl s_client -showcerts 确认服务端返回多张证书。


先确认新 Secret 已 apply 且命名空间正确,再检查 Ingress Controller 是否热加载,必要时执行 kubectl rollout restart。然后排除 CDN、负载均衡和本地 DNS 缓存,用 openssl s_client 查看 notAfter 是否已更新。


公有 TLS 证书受 CA/Browser Forum 规则约束,单张证书最长有效期 398 天;Let’s Encrypt 为 90 天短期证书。建议到期前 30 天续期,商业证书用流水线更新 Secret,ACME 证书用 cert-manager 自动续期。


cert-manager 主要面向 ACME 证书和内部 CA,是否支持 SSL.com 商业证书取决于 CA 是否提供 ACME 接口。多数 SSL.com 商业证书仍通过 fullchain.pem 和私钥导入 Secret,或用外部流水线自动化更新。

内容审核

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