跳到主要内容
Kubernetes

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。

内容审核

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