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,或用外部流水线自动化更新。