跳到主要内容
Kubernetes

ZeroSSL 证书部署 Kubernetes 实战:Ingress 挂载、cert-manager 自动续期与排错

问题背景与根因

ZeroSSL 提供 90 天免费 DV 证书,也提供付费 OV/EV;按 CA/Browser Forum 规则,所有公开信任的 TLS 证书最长有效期 398 天,ZeroSSL 免费 DV 与 Let’s Encrypt 均为 90 天。Kubernetes 本身不终止 TLS,真正加载证书的是 Ingress Controller(如 ingress-nginx)或云负载均衡。常见根因不是「证书没签下来」,而是 Secret 与 Ingress 不在同一 namespace、Ingress 的 secretName 拼错、上传了叶子证书而非 fullchain、私钥与证书不匹配,以及 cert-manager 使用 ZeroSSL ACME 时缺少 EAB。

Secret 只是 base64 存储,Controller 加载时才校验证书链与私钥;不同 Controller 的报错时机不同,所以要用 kubectl describe、Controller 日志和 openssl s_client 三层定位。续期后浏览器仍显示旧证书,多半是 Ingress Controller 缓存、CDN 回源或配置仍指向旧文件。ZeroSSL 网页端对新手友好、签发快;ACME 端要求 External Account Binding,适合 cert-manager 全自动。下面按「准备文件 → 创建 Secret/Ingress → cert-manager 自动签发 → 方案对比 → 排错 → 验证」走完整流程,命令可直接执行。

准备证书文件与校验

ZeroSSL 网页签发后通常得到 example.com.crt、ca_bundle.crt、private.key。部署到 K8s 前必须合成 fullchain:叶子证书在前,中间证书在后,不要拼根证书。若用 CSR 流程,CSR 的 CN 与 SAN 必须覆盖 Ingress 的 host,现代客户端只看 SAN,只写 CN 会报主机名不匹配。

openssl req -new -newkey rsa:2048 -nodes -keyout example.com.key -out example.com.csr -subj '/CN=example.com' -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'
cat example.com.crt ca_bundle.crt > fullchain.pem
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl verify -untrusted ca_bundle.crt example.com.crt
grep -c 'BEGIN CERTIFICATE' fullchain.pem

openssl verify 应返回 example.com.crt: OK;链文件计数通常为 2 或 3(叶子 + 中间证书,部分 CA 多一层)。再校验私钥是否匹配,RSA/ECDSA 都适用:

openssl x509 -in example.com.crt -noout -pubkey | openssl pkey -pubin -outform der | openssl md5
openssl pkey -in example.com.key -pubout -outform der | openssl md5

两条命令的 MD5 必须一致。若不一致,不要继续创建 Secret,直接重新签发或找回匹配私钥。注意:ZeroSSL 免费 DV 为 90 天,付费 OV/EV 也受 398 天上限约束;cert-manager 场景不需要手工下载,Secret 由 Certificate 资源生成。

用 kubectl 创建 TLS Secret 并配置 Ingress

Secret 必须与 Ingress 同 namespace。先创建命名空间和 Secret,再引用;tls.hosts 要与证书 SAN、Ingress rule 的 host 完全一致,通配符 *.example.com 只匹配一级子域。

kubectl create namespace web
kubectl create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key -n web
kubectl get secret example-com-tls -n web
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

更新证书不要直接 delete Secret,用 dry-run 滚动替换,避免 Ingress 短暂无证书:

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

ingress-nginx 会 watch Secret 并自动 reload;若使用文件挂载或自建 Controller,需 reload/restart 进程。检查 Ingress 事件中是否有 secret not found 或证书加载失败。

用 cert-manager 自动签发与续期

ZeroSSL ACME 要求 EAB(External Account Binding),且 ACME 主要签发 DV。先在 ZeroSSL Dashboard 的 Developer 页面获取 KID 与 HMAC Key,安装 cert-manager(版本按官方最新替换):

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.3/cert-manager.yaml
kubectl get pods -n cert-manager
kubectl create secret generic zerossl-eab -n cert-manager --from-literal=hmac-key='YOUR_HMAC_KEY'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: zerossl-prod
spec:
  acme:
    server: https://acme.zerossl.com/v2/DV90
    email: ops@example.com
    privateKeySecretRef:
      name: zerossl-prod-account-key
    externalAccountBinding:
      keyID: 'YOUR_KID'
      keyAlgorithm: HS256
      keySecretRef:
        name: zerossl-eab
        key: hmac-key
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx

Certificate 中 duration 设为 2160h(90 天),renewBefore 设为 720h(提前 30 天续期),并让 Ingress 通过 annotation 自动触发:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
  namespace: web
spec:
  secretName: example-com-tls
  duration: 2160h
  renewBefore: 720h
  commonName: example.com
  dnsNames:
    - example.com
    - www.example.com
  privateKey:
    algorithm: RSA
    size: 2048
    rotationPolicy: Always
  issuerRef:
    name: zerossl-prod
    kind: ClusterIssuer
metadata:
  annotations:
    cert-manager.io/cluster-issuer: zerossl-prod
kubectl apply -f certificate.yaml
kubectl get certificate,certificaterequest,order,challenge -n web
kubectl describe certificate example-com -n web

HTTP-01 要求 80 端口从公网可达;若域名在 CDN 后面或 80 被封,改用 DNS-01。OV/EV 需要人工审核,不能靠 ZeroSSL ACME 全自动,仍走网页签发后手工更新 Secret。

方案对比:手工 Secret 与 cert-manager

选择方案时重点看域名数量、续期频率和是否需要 OV/EV。所有公开信任证书最长 398 天,免费 DV 普遍 90 天,自动化续期是硬要求。

方案 有效期 续期方式 适用场景 主要风险
ZeroSSL 网页申请 + kubectl Secret 免费 DV 90 天;付费 OV/EV 最长 398 天 手动重签后 dry-run apply 少量域名、需要 OV/EV、临时测试 忘记续期、fullchain 拼错、私钥不匹配
cert-manager + ZeroSSL ACME DV 90 天 自动,建议 renewBefore 720h 多域名、动态 Ingress、全自动 EAB 配错、HTTP-01 不可达、速率限制
cert-manager + Let’s Encrypt DV 90 天 自动 通用 Web 服务 速率限制、ACME 账户问题
云厂商托管证书/负载均衡 依 CA,公开信任最长 398 天 平台自动 生产入口、少运维 厂商锁定、费用、回源证书不一致

若使用 Cloudflare 等代理,浏览器看到的是边缘证书,origin 的 ZeroSSL 证书要在回源侧验证;排查时用 –resolve 指向真实 Ingress IP,避免被 CDN 缓存误导。

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

先看三类日志:kubectl describe ingress/certificate、ingress-nginx Controller 日志、openssl s_client 实际握手。以下错误按出现频率排列。

  • curl: (60) SSL certificate problem: unable to get local issuer certificate 或 Java 报 PKIX path building failed。根因是只上传叶子证书,链不完整。执行 cat example.com.crt ca_bundle.crt > fullchain.pem,重建 Secret,并用 openssl verify -untrusted ca_bundle.crt example.com.crt 确认 OK。
  • nginx: [emerg] cannot load certificate … PEM_read_bio_X509_AUX() failed … no start line。Secret 中证书为空、格式错误或混入 CRLF。用 kubectl get secret example-com-tls -n web -o jsonpath='{.data.tls.crt}’ | base64 -d | openssl x509 -noout -subject 检查,失败则重新生成 PEM。
  • X509_check_private_key:key values mismatch。证书与私钥不是一对。用上文公钥 MD5 比对,重新签发或找回匹配私钥,再 dry-run apply。
  • local SSL certificate default/example-com-tls was not found。Secret 与 Ingress 不同 namespace,或 secretName 拼错。kubectl get secret -A | grep example-com-tls 定位,确保 tls.secretName 与 Ingress 同 namespace。
  • 403 urn:ietf:params:acme:error:unauthorized: EAB HMAC key is invalid。ZeroSSL EAB 的 KID/HMAC 复制错误,或 Secret 不在 cert-manager namespace。重建 zerossl-eab,检查 kubectl logs -n cert-manager deploy/cert-manager。
  • Challenge 一直 pending / HTTP 404。80 端口未放行、Ingress class 不匹配或 CDN 拦截 /.well-known/acme-challenge/。kubectl describe challenge -n web 查看 Reason,并用 curl -v http://example.com/.well-known/acme-challenge/test 验证。

续期后不生效时,先确认 Secret 的 notAfter 已更新,再 reload/restart Controller;CDN 场景还要刷新边缘证书。

效果验证与续期检查

cert-manager 场景先看 Certificate 状态与续期时间:

kubectl get certificate -A
kubectl describe certificate example-com -n web | grep -E 'Status|Renewal Time|Not After'
kubectl get secret example-com-tls -n web -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

从集群外验证实际握手,不要只看浏览器。–resolve 可绕过 DNS/CDN,直连 Ingress IP:

curl -vI --resolve example.com:443:203.0.113.10 https://example.com
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -issuer -subject -dates
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
curl -sI http://example.com | head -n 1

链计数应大于等于 2;最后一条应返回 301/308,说明 ssl-redirect 生效。若 cert-manager 的 Renewal Time 不是到期前约 30 天,检查 renewBefore 是否被 Certificate 覆盖。生产环境建议加监控:对 Secret 的 notAfter 做告警,剩余 21 天仍未续期即介入。

常见问题

ZeroSSL 免费 DV 证书有效期为 90 天;公开信任 TLS 证书最长 398 天。用 cert-manager 时设置 duration: 2160h、renewBefore: 720h,到期前约 30 天自动续期,避免手工漏续。


ZeroSSL ACME 要求 External Account Binding。到 Dashboard 的 Developer 页面取 KID 与 HMAC Key,把 HMAC 放进 cert-manager namespace 的 Secret,再在 ClusterIssuer 的 externalAccountBinding 中引用;KID/HMAC 错会报 EAB HMAC key is invalid。


先确认 Secret 与 Ingress 在同一 namespace,再核对 tls.secretName 拼写。执行 kubectl get secret -A | grep example-com-tls 和 kubectl describe ingress example-ingress -n web;跨 namespace 不能直接引用,需在本 namespace 重建 Secret。


多半是链不完整。用 fullchain.pem(叶子在前、中间证书在后)重建 Secret,执行 openssl verify -untrusted ca_bundle.crt example.com.crt 应返回 OK;Java 报 PKIX path building failed 时重点查中间证书。


先看 Secret 的 notAfter 是否已更新,再查 Ingress Controller 是否 reload;ingress-nginx 通常自动 watch,异常时可 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx。CDN 场景还要刷新边缘证书。


ZeroSSL ACME 主要面向 DV,OV/EV 需要人工审核,通常网页申请后手工更新 Secret;有效期仍受 398 天上限约束。域名多时建议 DV 走 cert-manager,OV/EV 单独做到期监控。

内容审核

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