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 单独做到期监控。