Let’s Encrypt SSL 证书在 Kubernetes 中安装部署实战:Ingress、cert-manager 与排错
问题背景与根因:为什么 K8s 中 Let’s Encrypt 证书容易“签发成功但不生效”
Let’s Encrypt 是免费 DV 证书,单张有效期 90 天,通过 ACME 协议自动签发与续期;公共可信 TLS 证书最长有效期目前为 398 天,因此 90 天证书必须依赖自动化续期。Kubernetes 中证书不是“装到服务器某个目录”就结束,而是以 kubernetes.io/tls 类型的 Secret 保存 tls.crt 与 tls.key,再由 Ingress 或 Ingress Controller 引用。常见根因有四类:一是 Secret 中只放了叶子证书,没有放中间证书,浏览器可能正常,但 curl、Java、小程序校验失败;二是 Ingress 的 secretName、命名空间或 ingressClassName 不一致,导致控制器没有加载证书;三是 ACME HTTP-01 校验要求域名 80 端口可访问 /.well-known/acme-challenge/,被 WAF、NetworkPolicy、重定向或路径重写拦截后签发失败;四是续期后 Secret 已更新,但 Ingress Controller 未 reload 或缓存未刷新。cert-manager 通过 Certificate、CertificateRequest、Order、Challenge 资源把 ACME 流程对象化,适合生产;手动 kubectl create secret tls 只适合临时验证。理解这条链路,才能定位“证书已签发但 HTTPS 仍旧证书”的问题。
完整实操步骤:从 cert-manager 安装到 Ingress 自动签发
以下命令可直接执行,示例域名 example.com,命名空间 default,Ingress Controller 为 ingress-nginx。第一步安装 cert-manager,并等待 Webhook 就绪:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.3/cert-manager.yaml
kubectl -n cert-manager rollout status deploy/cert-manager
kubectl -n cert-manager get pods
kubectl get apiservice | grep cert-manager
第二步先用 staging 环境验证 ACME 流程,避免触发生产速率限制。创建 ClusterIssuer:
kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
server: https://acme-staging-v02.api.letsencrypt.org/directory
email: ops@example.com
privateKeySecretRef:
name: letsencrypt-staging-account-key
solvers:
- http01:
ingress:
class: nginx
EOF
这里用了 heredoc,包含 <<'EOF',在 HTML 中已转义。第三步给 Ingress 增加注解 cert-manager.io/cluster-issuer: letsencrypt-staging,并确保 spec.tls.secretName 为 example-com-tls。应用后观察证书资源:
kubectl get certificate,certificaterequest,order,challenge -A
kubectl describe certificate example-com-tls -n default
kubectl describe challenge -n default
当 Ready=True 后,把注解改为 letsencrypt-prod,并删除 staging 生成的 Secret 与 Certificate,让 cert-manager 重新向生产 ACME 申请:
kubectl delete secret example-com-tls -n default
kubectl delete certificate example-com-tls -n default
kubectl annotate ingress web cert-manager.io/cluster-issuer=letsencrypt-prod --overwrite
kubectl get certificate -n default -w
若不用 cert-manager,可用 certbot 的 webroot 或 DNS 插件先申请,再导入 Secret:
certbot certonly --webroot -w /var/www/html -d example.com --email ops@example.com --agree-tos --no-eff-email
kubectl create secret tls example-com-tls --cert=/etc/letsencrypt/live/example.com/fullchain.pem --key=/etc/letsencrypt/live/example.com/privkey.pem -n default --dry-run=client -o yaml | kubectl apply -f -
注意 --cert 必须指向 fullchain.pem,不是 cert.pem。手动方式还需用 CronJob 或外部脚本续期并滚动更新 Secret,否则 90 天到期后直接中断。cert-manager 默认在证书剩余约 30 天时续期,更适合 K8s。
配置示例:ClusterIssuer、Certificate 与 Ingress 可直接套用
生产环境建议将 staging 与 prod 分开。下面是生产 ClusterIssuer,ACME 目录为 https://acme-v02.api.letsencrypt.org/directory,HTTP-01 solver 指定 ingress-nginx 的 class:
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: ops@example.com
privateKeySecretRef:
name: letsencrypt-prod-account-key
solvers:
- http01:
ingress:
class: nginx
Ingress 侧只需声明 TLS 与注解。以下配置会把 example.com 的 HTTP 请求 308 重定向到 HTTPS,并让 cert-manager 自动创建同名 Certificate:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: default
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
nginx.ingress.kubernetes.io/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
如果服务不在 Ingress 后面,或需要为多个域名、通配符单独签发,可显式创建 Certificate。注意 issuerRef.kind 是 ClusterIssuer 时跨命名空间可用;若是命名空间级 Issuer,则必须与 Certificate 同命名空间:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com-tls
namespace: default
spec:
secretName: example-com-tls
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
commonName: example.com
dnsNames:
- example.com
- www.example.com
通配符证书如 *.example.com 必须使用 DNS-01,不能走 HTTP-01。cert-manager 的 DNS-01 solver 需要云厂商 API 凭据,例如 Route53、Cloudflare 或阿里云 DNS,凭据放入 Secret 后在 solvers.dns01 中引用。配置完成后执行 kubectl apply -f ingress.yaml,再用 kubectl get certificate -n default 检查 READY 列。生产环境不要把 email 写成无效地址,ACME 账户过期通知和吊销通知会发送到该邮箱。证书 Secret 名不要与已有 Secret 冲突,否则 cert-manager 会拒绝覆盖非自己管理的 Secret。
方案对比:手动 Secret、cert-manager 与 certbot/acme.sh
选择方案时先看域名数量和 80 端口条件。单域名且 80 端口可公网访问,cert-manager 配合 HTTP-01 最省事;通配符或 80 端口被禁用,必须用 DNS-01。下表给出常见组合的取舍:
| 方案 | 适用场景 | 优点 | 注意 |
|---|---|---|---|
手动 kubectl create secret tls |
临时测试、无 cert-manager 权限 | 简单直接,不依赖 CRD | 90 天续期需人工或 CronJob;易漏 fullchain;Secret 更新后需 controller reload |
| cert-manager + Ingress 注解 | 生产 K8s、标准单域名 | 自动签发续期,Certificate/Order/Challenge 可排错 | 需安装 CRD 与 Webhook;HTTP-01 要求 80 端口可达;注意生产 rate limit |
| certbot/acme.sh + Secret | 已有 ACME 脚本、混合环境 | 工具成熟,支持 webroot 与 DNS 插件 | 需自建续期流水线,并跨命名空间分发 Secret |
| DNS-01 | 通配符、80 端口不可用 | 不依赖入站 80 端口 | 需 DNS API 权限,凭据要最小化并加密保存 |
再对比 ACME 校验方式:
| 校验方式 | 要求 | 适用 | 常见失败点 |
|---|---|---|---|
| HTTP-01 | 80 端口可访问 /.well-known/acme-challenge/ |
单域名、常规 Ingress | WAF、重定向、路径重写、NetworkPolicy |
| DNS-01 | 可写 _acme-challenge TXT 记录 |
通配符、内网入口 | DNS API 权限不足、传播延迟、CNAME 冲突 |
价格上 Let’s Encrypt 是免费 DV,不提供 OV/EV 人工审核与保障金;公共可信证书最长 398 天,而 Let’s Encrypt 固定 90 天,所以自动化不是可选项。生产建议 cert-manager 管理,临时验证才用手动 Secret。若企业要求 OV/EV 或更长有效期,需要商业 CA,但同样要遵守 398 天上限并建立续期流程。
常见错误排查:真实报错与修复命令
报错一:curl: (60) SSL certificate problem: unable to get local issuer certificate,或 Go 服务报 x509: certificate signed by unknown authority。根因通常是 Secret 的 tls.crt 只包含叶子证书,缺少中间证书。检查链:
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | openssl x509 -noout -issuer -subject -dates
kubectl get secret example-com-tls -n default -o yaml | grep -c 'BEGIN CERTIFICATE'
正常 fullchain 应至少包含两张证书。手动创建 Secret 时用 fullchain.pem,不要用 cert.pem。报错二:tls: private key does not match public key。RSA 证书核对模数:
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
两个 MD5 必须一致;不一致说明证书与私钥不是同一次生成。若为 ECDSA,改用公钥比对:openssl x509 -in fullchain.pem -pubkey -noout | openssl md5 与 openssl pkey -in example.com.key -pubout | openssl md5。报错三:ACME challenge ... 404。执行 kubectl describe challenge -n default 查看 Reason,再检查 Ingress class 是否为 nginx、Service 端口是否指向 80、/.well-known/acme-challenge/ 是否被 WAF 或 rewrite 拦截。HTTP-01 还要求域名解析到当前 Ingress 入口,且 80 端口对公网可达。报错四:urn:ietf:params:acme:error:rateLimited。说明生产环境申请过频,先切 staging 验证,等待限制窗口结束,不要反复删除重建。报错五:secret 'example-com-tls' not found。检查 Ingress 与 Secret 是否同命名空间,spec.tls.secretName 是否拼写一致。续期后不生效时,先看 Secret 的 resourceVersion 是否变化,再重启控制器:
kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx
kubectl get secret example-com-tls -n default -o yaml | grep -E 'resourceVersion|tls.crt'
若使用云负载均衡,还要确认证书是在 Ingress Controller 终止,还是在 LB 终止;在 LB 终止时,K8s 内 Secret 更新不会自动同步到云证书服务。
效果验证:确认证书链、有效期与自动续期
先看 cert-manager 对象状态:kubectl get certificate -A 的 READY 应为 True,kubectl describe certificate example-com-tls -n default 的 Events 应出现 Certificate is up to date and has not expired。查看续期时间:
kubectl get certificate example-com-tls -n default -o jsonpath='{.status.renewalTime}'
kubectl get certificaterequest,order,challenge -A
再验证 Secret 内证书主题、签发者与有效期。Let’s Encrypt 证书有效期 90 天,公共可信证书上限 398 天,因此 notAfter 与 notBefore 相差应在 90 天左右:
kubectl get secret example-com-tls -n default -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
如果 JSONPath 转义不便,也可直接导出 YAML 后解码。线上握手验证要带 SNI,否则多域名入口可能返回默认证书:
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | openssl x509 -noout -issuer -subject -dates
curl -vI https://example.com
curl -I http://example.com
curl -vI 应看到 SSL certificate verify ok,HTTP 请求应返回 301 或 308 跳转到 HTTPS。检查证书链是否完整:
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | grep 'Verify return code'
输出 Verify return code: 0 (ok) 才表示链完整。最后模拟续期:对 staging 证书可删除 Secret 触发重签;生产环境不要频繁删除,应依赖 renewBefore 或 cert-manager 自动续期。观察 kubectl get certificate -w 与 kubectl logs -n cert-manager deploy/cert-manager,确认续期后 Ingress Controller 已加载新证书。若使用外部监控,建议对 notAfter 做告警,阈值设为剩余 21 天,早于 cert-manager 默认约 30 天续期窗口,避免续期失败无人发现。
常见问题
Let’s Encrypt 证书有效期为 90 天,公共可信 TLS 证书最长有效期为 398 天。cert-manager 默认在到期前约 30 天自动续期,因此不要把手动 Secret 当作长期方案;应监控 Certificate 的 READY 与 renewalTime,避免 90 天到期后服务中断。
生产 K8s 优先用 cert-manager,它通过 Ingress 注解或 Certificate 资源自动签发、续期并更新 Secret。手动 kubectl create secret tls 只适合临时测试或无 CRD 权限的环境,且必须自建 CronJob 续期,并确保使用 fullchain.pem 与正确私钥。
先执行 kubectl describe challenge 查看 Reason,再确认域名解析到当前 Ingress 入口、80 端口公网可达、ingressClassName 与 solver 的 class 一致,以及 /.well-known/acme-challenge/ 未被 WAF、重定向或 rewrite 拦截。通配符证书改用 DNS-01。
通常是 Secret 的 tls.crt 只放了叶子证书。应改用 fullchain.pem 创建 Secret,并用 openssl s_client -showcerts 检查服务端是否返回中间证书;同时确认客户端信任库包含对应根证书。
先确认 Secret 的 resourceVersion 已变化,再检查 Ingress Controller 是否监听该 Secret。可执行 kubectl rollout restart deploy/ingress-nginx-controller -n ingress-nginx 触发 reload;若 TLS 在云负载均衡终止,还需把新证书同步到云证书服务。