ZeroSSL 证书部署 Kubernetes 实战:Secret、Ingress 与 cert-manager 自动续期
问题背景与根因:为什么 ZeroSSL 证书在 K8s 里“签发成功但访问失败”
ZeroSSL 提供 90 天免费 DV 证书(ACME 或网页签发)以及付费 OV/EV;免费证书适合快速上线,但 Kubernetes 不会自动理解网页下载的压缩包。K8s 的 TLS 落点是 kubernetes.io/tls 类型的 Secret,Ingress Controller 在入口处终止 TLS,因此 Secret 中的 tls.crt 必须是“叶子证书 + 中间证书”的 fullchain,tls.key 必须与叶子证书匹配。最常见的根因不是证书没签发,而是:只上传了叶子证书导致链不完整、Secret 与 Ingress 不在同一 namespace、IngressClass 不匹配、控制器缓存未刷新,或误把 ZeroSSL 的 CA bundle 当成了完整链。注意 CA/B 规则下 TLS 证书最长有效期 398 天,ZeroSSL 免费 DV 与 Let’s Encrypt 均为 90 天,续期必须纳入运维流程。若 Secret 类型不是 kubernetes.io/tls,部分控制器不会加载;可用 kubectl get secret example-com-tls -n web -o jsonpath='{.type}' 验证。先确认集群与入口类:kubectl version、kubectl get ingressclass。
准备工作:从 ZeroSSL 获取证书并整理 fullchain 与私钥
网页端签发后通常得到 certificate.crt、ca_bundle.crt、private.key;ACME 客户端则直接得到 fullchain。无论哪种方式,部署前执行三件事:拼接、校验链、校验密钥匹配。命令如下:
cat certificate.crt ca_bundle.crt > fullchain.pem
openssl verify -untrusted ca_bundle.crt certificate.crt
openssl x509 -noout -subject -issuer -dates -in fullchain.pem
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in private.key | openssl md5
两条 modulus 的 MD5 必须一致;ECDSA 证书改用 openssl x509 -noout -pubkey -in fullchain.pem | openssl md5 与 openssl pkey -pubout -in private.key | openssl md5 对比。若 openssl verify 返回 error 20 at 0 depth lookup: unable to get local issuer certificate,说明中间证书顺序或文件不对,不要继续创建 Secret。私钥权限设为 chmod 600 private.key,并确认证书 SAN 覆盖 example.com 与 www.example.com;ZeroSSL 免费 DV 有效期 90 天,建议在到期前 30 天续期。
完整实操:用 kubectl 创建 TLS Secret 并挂到 Ingress
先创建命名空间,再用 --dry-run=client -o yaml | kubectl apply -f - 实现幂等更新。直接执行 kubectl create secret tls 在 Secret 已存在时会报 Error from server (AlreadyExists): secrets "example-com-tls" already exists,所以生产环境用 dry-run 管道:
kubectl create namespace web --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret tls example-com-tls --cert=fullchain.pem --key=private.key -n web --dry-run=client -o yaml | kubectl apply -f -
kubectl get secret example-com-tls -n web -o jsonpath='{.type}'
kubectl describe secret example-com-tls -n web
输出类型应为 kubernetes.io/tls,且 Data 中包含 tls.crt 与 tls.key。随后部署 Ingress,确保 spec.tls[].secretName 与 Secret 名称、namespace 完全一致;Ingress 与 Secret 必须同 namespace。若使用 NGINX Ingress,确认 ingressClassName: nginx 与集群中的 IngressClass 一致,否则控制器不会加载该规则。更新 Secret 后控制器通常自动热加载,若未生效可执行 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx 并观察日志。
配置示例:Ingress、IngressClass 与 cert-manager 自动签发
手工 Secret 的 Ingress 示例如下,ssl-redirect 与 force-ssl-redirect 同时开启可避免 HTTP 明文访问:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
namespace: web
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: 'true'
nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
spec:
ingressClassName: nginx
tls:
- hosts:
- example.com
secretName: example-com-tls
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
若用 cert-manager 对接 ZeroSSL ACME,先创建 EAB Secret,再建 ClusterIssuer 与 Certificate。ZeroSSL ACME 端点 https://acme.zerossl.com/v2/DV90 通常需要 EAB:
kubectl create secret generic zerossl-eab -n cert-manager --from-literal=secret='EAB_HMAC_KEY'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: zerossl-prod
spec:
acme:
email: ops@example.com
server: https://acme.zerossl.com/v2/DV90
privateKeySecretRef:
name: zerossl-account-key
externalAccountBinding:
keyID: EAB_KID
keySecretRef:
name: zerossl-eab
key: secret
solvers:
- http01:
ingress:
class: nginx
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com
namespace: web
spec:
secretName: example-com-tls
issuerRef:
name: zerossl-prod
kind: ClusterIssuer
dnsNames:
- example.com
renewBefore: 720h
Certificate 中设置 secretName: example-com-tls、dnsNames 和 renewBefore: 720h,cert-manager 会生成同名 Secret 并被 Ingress 引用。用 kubectl get certificate,order,challenge -n web 查看状态。
对比表格:手动 Secret、cert-manager 与 Ingress 注解怎么选
三种落地方式的差异如下,生产环境优先 cert-manager,临时验证可用手工 Secret:
| 方式 | 核心命令/资源 | 续期 | 适用场景 |
|---|---|---|---|
| 手动 Secret | kubectl create secret tls ... --dry-run=client -o yaml | kubectl apply -f - |
人工,90 天证书建议 60-80 天更新 | 测试、少量域名 |
| cert-manager | Certificate + ClusterIssuer |
自动,renewBefore: 720h |
生产多域名 |
| Ingress 注解 | cert-manager.io/cluster-issuer |
自动创建 Certificate | 快速接入 |
证书产品侧也要区分:ZeroSSL 免费 DV 90 天、支持 ACME 但通常要 EAB;Let’s Encrypt 免费 DV 90 天、ACME 无需 EAB;ZeroSSL 付费 OV/EV 可提供组织验证。无论哪家,CA/B 规则下 TLS 证书最长有效期 398 天,所谓“买多年”只是订阅期,实际证书仍需轮换。若证书链不完整,浏览器可能因 AIA 补链而正常,但 Java、Go、小程序等严格客户端会失败。
| 项目 | ZeroSSL 免费 DV | Let’s Encrypt |
|---|---|---|
| 有效期 | 90 天 | 90 天 |
| ACME | 支持,通常需 EAB | 支持,无需 EAB |
| 付费 OV/EV | 支持 | 不提供 |
| 最长有效期规则 | 受 398 天上限约束 | 同 |
常见错误排查:真实报错与修复命令
先看入口控制器日志:kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=100。高频报错如下:
| 报错 | 根因 | 修复 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
tls.crt 只有叶子证书,缺中间证书 | 用 fullchain 重建 Secret,openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 确认至少返回 2 张证书 |
x509: certificate signed by unknown authority |
Go 客户端校验失败,链不完整或根不受信 | 补全 intermediate;不要把手动根证书塞进 fullchain |
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target |
Java truststore 不信任该链 | 先修服务端链,再把根/中间证书导入 truststore |
error: failed to load key pair: tls: private key does not match public key |
证书与私钥不匹配 | 对比 modulus MD5;ECDSA 对比公钥 MD5 |
SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) |
Secret 中 crt/key 来自不同批次 | 重新生成 Secret 并 rollout restart 控制器 |
若出现 default backend - 404,优先检查 host、pathType、Service 端口和 ingressClassName,而不是证书。续期后仍显示旧证书时,用 kubectl get secret ... -o yaml 看 resourceVersion 是否变化,再确认 Ingress 引用的 secretName 没有指向旧 Secret。
效果验证:从集群内到公网逐层确认证书链
验证顺序应为 Secret → Ingress → 控制器 → 公网。先看证书资源与 Secret 内容:
kubectl get certificate -A
kubectl describe certificate example-com -n web
kubectl get secret example-com-tls -n web -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
curl -vI https://example.com
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -issuer -dates
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null
kubectl run curl-test --image=curlimages/curl:8.8.0 --restart=Never --rm -it -- curl -vI https://example.com
kubectl get certificate -A 中 cert-manager 管理的证书应为 Ready=True;curl -vI 应看到 SSL certificate verify ok 与到期时间。若公网 curl 正常但集群内失败,检查 CoreDNS、NetworkPolicy 与出口代理;若集群内正常但公网失败,检查 LB、CDN、WAF 是否终止了 TLS 或仍缓存旧证书。最后用 openssl s_client -verify_return_error 做严格校验,并确认有效期不超过 398 天、ZeroSSL 免费 DV 为 90 天。
常见问题
ZeroSSL 免费 DV 证书有效期为 90 天,可通过 ACME 客户端或 cert-manager 自动续期;建议设置 renewBefore: 720h,在到期前 30 天触发。手工 Secret 方式不会自动续期,需要重新下载并更新 Secret。
应放 fullchain,即叶子证书在前、中间证书在后。只放叶子证书时,浏览器可能靠 AIA 补链正常,但 curl、Java、Go、小程序等严格客户端会报 unable to get local issuer certificate 或 PKIX 错误。
先确认 Secret 的 resourceVersion 已变化,且 Ingress 的 secretName 指向新 Secret;再检查 Ingress Controller 是否热加载,可执行 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx,并清理 CDN/WAF 缓存。
两者免费 DV 均为 90 天。Let’s Encrypt ACME 接入简单、无需 EAB;ZeroSSL 网页签发友好,ACME 通常需要 EAB,并提供付费 OV/EV。生产环境更关键是选 cert-manager 自动续期和完整证书链。
通常是服务端未发送中间证书,浏览器通过 AIA 自动补链,而 Java 严格按 truststore 校验。修复方式是 tls.crt 使用 fullchain,必要时再把根证书或中间证书导入 Java truststore。