跳到主要内容
Kubernetes

Let’s Encrypt 证书部署到 Kubernetes 实战:Ingress、cert-manager 与排错指南

问题背景与根因:为什么 K8s 部署 Let’s Encrypt 证书容易踩坑

Let’s Encrypt 是免费 DV 证书,当前签发有效期固定为 90 天,依赖 ACME 协议自动续期;公共信任 TLS 证书受行业规则约束,单张证书最长有效期不超过 398 天,因此把 90 天证书手工放进 Kubernetes Secret 后忘记续期,是最常见的线上事故来源。Kubernetes 中证书以 Secret 形式与 Ingress 解耦,问题往往不在证书本身,而在引用链:Secret 命名空间错误、Ingress 的 secretName 拼写不一致、Ingress Controller 未监听该 Secret、证书链只放了叶子证书、私钥与证书不匹配、HTTP-01 Challenge 被 WAF 或路由拦截,都会表现为浏览器报 SSL 错误、curl 报 x509、Java 报 PKIX path building failed。

根因可以归纳为三类:第一,证书材料不完整。Kubernetes 的 tls 类型 Secret 需要 cert 为 fullchain.pem,key 为私钥;只上传 leaf 证书时,桌面浏览器可能靠 AIA 补齐中间证书,但 curl、Java、小程序、Go 客户端会直接失败。第二,域名与路由不一致。ACME HTTP-01 校验要求 http://example.com/.well-known/acme-challenge/ 能返回 200,如果 Ingress 把该路径重写到后端、开启全站 HTTPS 强制跳转、或 IngressClass 不匹配,Challenge 就会 404。第三,续期没有闭环。手动 Secret 更新后,部分 Ingress Controller 需要 reload;cert-manager 虽然自动续期,但 Certificate 的 secretName、dnsNames、issuerRef 写错时,状态会停在 False。

排查时先看对象状态,而不是先重签证书:

kubectl get certificate -A
kubectl get secret -A | grep -E 'tls|example-com'
kubectl describe ingress example-ingress -n production
kubectl get events -n production --sort-by=.lastTimestamp | tail -30

如果使用 cert-manager,再执行 kubectl get challenge,order -A 查看 ACME 流程卡在哪一步。把证书有效期、SAN、链、私钥匹配四项校验做完,再动 Ingress 配置,能避免大部分无效重试。

准备工作:ACME 客户端、域名与 Ingress 前置检查

先确认域名解析和入口。假设域名 example.com 和 www.example.com 的 A 记录指向 Ingress Controller 的负载均衡 IP,80/443 已放行。执行:

dig +short example.com
dig +short www.example.com
kubectl get ingressclass
kubectl get svc -n ingress-nginx ingress-nginx-controller
curl -I http://example.com/.well-known/acme-challenge/health-check

最后一条返回 404 是正常的,说明请求已经到达 Ingress;如果返回 301 到 HTTPS,需要为 ACME 路径放行 HTTP,或改用 DNS-01。IngressClass 名称必须与 Ingress 的 ingressClassName 一致,常见值为 nginx。

选择 ACME 客户端。小规模单集群可以用 certbot 或 acme.sh 在集群外签发,再创建 Secret;多命名空间、多团队建议用 cert-manager。以 acme.sh 为例,签发命令为:

acme.sh --issue -d example.com -d www.example.com --standalone --keylength 2048
acme.sh --install-cert -d example.com --key-file example.com.key --fullchain-file fullchain.pem --reloadcmd 'kubectl create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key -n production --dry-run=client -o yaml | kubectl apply -f -'

注意 fullchain.pem 必须包含中间证书,不能只取 cert.pem。若使用 DNS-01,需要给 ACME 客户端配置 DNS API 凭据,适合通配符证书 *.example.com。

手动生成 CSR 只用于排查或企业 CA 场景,Let’s Encrypt 由 ACME 客户端自动完成 CSR。可用以下命令核对私钥和 SAN:

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'
openssl req -in example.com.csr -noout -text | grep -A2 'Subject Alternative Name'

如果域名有 CAA 记录,确认允许 letsencrypt.org;企业网络还需放行 outbound 443 到 acme-v02.api.letsencrypt.org。完成这些检查后再创建 Secret,能减少 Challenge 失败和证书链错误。

手动方式:用 kubectl 创建 TLS Secret 并接入 Ingress

准备 fullchain.pem 和 example.com.key 后,用声明式方式创建 Secret,避免重复执行报 AlreadyExists:

kubectl create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key -n production --dry-run=client -o yaml | kubectl apply -f -
kubectl get secret example-com-tls -n production -o jsonpath='{.type}'
# 输出应为 kubernetes.io/tls

Secret 必须和 Ingress 在同一命名空间。若 Ingress 在 default,Secret 在 production,控制器会报 secret not found。检查 Secret 内容:

kubectl get secret example-com-tls -n production -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -subject -issuer -dates

Ingress 配置示例,关键点是 tls.hosts、secretName、ingressClassName 和 ssl-redirect:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: 'true'
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - example.com
        - www.example.com
      secretName: example-com-tls
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

执行 kubectl apply -f ingress.yaml,再用 kubectl describe ingress example-ingress -n production 查看 TLS 段是否引用了正确 Secret。

续期更新时重新执行第一条 create secret 命令即可。nginx ingress controller 会 watch Secret 变化并重新加载;如果 curl 仍看到旧证书,执行

kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller
kubectl rollout status deployment -n ingress-nginx ingress-nginx-controller

其他控制器可能需要重启对应 Pod。手动方式必须配合 cron 或 systemd timer,在到期前至少 30 天续期,否则 90 天有效期一到就会中断。

自动化方式:cert-manager 安装与 ClusterIssuer/Certificate 配置

cert-manager 是 Kubernetes 原生证书管理控制器,通过 CRD 自动完成 ACME 签发和续期。安装稳定版本:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.3/cert-manager.yaml
kubectl get pods -n cert-manager
kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=180s

确认三个 Pod 为 Running:cert-manager、cert-manager-cainjector、cert-manager-webhook。接着创建 ClusterIssuer,生产环境使用 Let’s Encrypt production 目录,测试先用 staging 避免触发速率限制:

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:
            ingressClassName: nginx

执行 kubectl apply -f issuer.yaml,然后 kubectl get clusterissuer 应看到 READY=True。

推荐用 Certificate 资源而不是只在 Ingress 上加 annotation,便于独立管理续期和 SAN:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-tls
  namespace: production
spec:
  secretName: example-com-tls
  duration: 2160h
  renewBefore: 720h
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - example.com
    - www.example.com

duration 2160h 即 90 天,renewBefore 720h 即提前 30 天续期。应用后执行 kubectl get certificate -n production,READY 应为 True;kubectl describe certificate 会显示 Renewal Time。若用 Ingress annotation,可写 cert-manager.io/cluster-issuer: letsencrypt-prod,但 SAN 由 tls.hosts 决定,排错时不如 Certificate 直观。

cert-manager 会自动创建 Order、Challenge 和临时 Ingress。用 kubectl get challenge -n production 查看状态;HTTP-01 通过后 Secret 才会生成。注意 Let’s Encrypt 生产环境有速率限制,例如同一注册域名每周 50 张证书,调试阶段务必用 staging 目录:https://acme-staging-v02.api.letsencrypt.org/directory。

证书链、私钥匹配与续期机制:关键校验命令

证书链不完整是最隐蔽的问题。fullchain.pem 的顺序应为叶子证书在前、中间证书在后。检查命令:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
openssl verify -CAfile fullchain.pem fullchain.pem

第一条输出 SAN 必须覆盖实际访问域名;第二条应看到至少两张证书;第三条返回 OK 表示本地链可验证。只上传 leaf 时,openssl s_client 可能显示 verify error 20,Java 和 curl 会失败。服务器侧验证:

openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates

如果 issuer 是 R3 或 E5 等中间 CA,而客户端只收到一张证书,就是链缺失。

私钥匹配用模数比对,RSA 和 ECDSA 都适用:

openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5

两行 md5 必须一致;不一致时 Kubernetes 会报 tls: private key does not match public key。ECSDA 私钥可用 openssl pkey -in example.com.key -pubout | openssl md5 与证书公钥比对。

续期机制要分清两条路径。手动 Secret 依赖外部 cron 执行 acme.sh –renew 或 certbot renew,然后重新 kubectl create secret;cert-manager 根据 Certificate 的 renewBefore 自动续期,默认在到期前 30 天左右发起,90 天证书对应 duration 2160h。续期后检查:

kubectl get certificate -n production -o wide
kubectl describe certificate example-com-tls -n production | grep -E 'Renewal Time|Not After|Status'
kubectl get secret example-com-tls -n production -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -enddate

如果 Renewal Time 已过但未更新,查看 cert-manager 日志:kubectl logs -n cert-manager deploy/cert-manager –tail=100。公共 TLS 证书最长 398 天的规则对 Let’s Encrypt 的 90 天证书没有额外影响,但企业 CA 签发时需注意不要超过上限。

手动 Secret 与 cert-manager 方案对比

选择方案时不要只看能不能签发,要看续期失败后的可观测性和多团队权限。下表按生产关注点对比:

维度 手动 kubectl Secret + acme.sh/certbot cert-manager
签发入口 集群外 cron 或 CI 执行 ACME Kubernetes CRD(Issuer/ClusterIssuer、Certificate)
续期 依赖 cron、脚本和 kubectl 权限 控制器自动续期,默认提前约 30 天
失败可观测性 看脚本日志和 Secret 更新时间 Certificate/Order/Challenge 状态与 Events
多命名空间 每个命名空间重复授权 Secret ClusterIssuer 共用,Certificate 按命名空间隔离
通配符证书 acme.sh 配 DNS API 即可 需配置 DNS-01 solver 和 DNS 凭据 Secret
权限风险 CI 持有 kubeconfig 和私钥 私钥留在集群 Secret,RBAC 可控
适用场景 单集群、少量域名、已有成熟发布流水线 多团队、多 Ingress、需要自动续期闭环

HTTP-01 与 DNS-01 也要选对。HTTP-01 配置简单,要求 80 端口可达且域名解析到该 Ingress;DNS-01 适合通配符、内网入口或 80 被封锁的场景,但需要 DNS 服务商 API。cert-manager 的 HTTP-01 solver 会创建临时 Ingress 和 Service,若集群有 NetworkPolicy 或 WAF,需要放行 /.well-known/acme-challenge/ 路径。手动方案在证书更新后还要考虑 Ingress Controller 是否 reload;cert-manager 更新 Secret 后同样依赖控制器监听。无论哪种方案,都建议保留 staging 环境验证 ACME 流程,避免生产目录触发 too many certificates already issued 速率限制。

成本上,Let’s Encrypt 证书本身免费,主要成本是运维自动化和监控。手动方案脚本维护成本高,cert-manager 学习曲线高但长期更稳。若组织已有商业 CA 和 398 天证书,也可用 cert-manager 的 CA Issuer 或 Venafi 集成,但公共信任场景仍建议优先 ACME 自动化。

常见错误排查:真实报错与修复命令

按报错定位比反复重签有效。以下是最常见的六类:

1)curl: (60) SSL certificate problem: unable to get local issuer certificate。说明服务端没有发送中间证书。修复:确认 Secret 的 tls.crt 是 fullchain.pem,而不是 cert.pem;执行 kubectl get secret … | base64 -d | openssl crl2pkcs7 -nocrl -certfile /dev/stdin | openssl pkcs7 -print_certs -noout 应看到两张以上证书。

2)x509: certificate signed by unknown authority。常见于 Go 服务调用内部域名,或客户端信任库没有对应根证书。先跑 openssl s_client -connect example.com:443 -servername example.com -showcerts 检查链;若链完整,检查客户端 CA 包是否更新。

3)Java 报 PKIX path building failed。Java 默认信任库缺少中间证书或根证书。用 keytool -importcert -alias example -file intermediate.crt -keystore cacerts 导入,或让服务端发送完整链。不要关闭 TLS 校验来解决问题。

4)小程序 request:fail ssl hand shake error。检查 TLS 版本是否低于 1.2、证书链是否完整、域名是否与 SAN 一致;微信小程序要求 HTTPS 且证书受信任。用 openssl s_client -tls1_2 验证。

5)cert-manager Challenge 一直 Pending,describe challenge 显示 Waiting for HTTP-01 challenge propagation: wrong status code ‘404’。说明 ACME 校验请求没有命中临时 Ingress。检查 ingressClassName 是否为 nginx、/.well-known/acme-challenge/ 是否被重写或跳转、WAF 是否拦截。命令:kubectl get challenge,order -n production;kubectl describe challenge -n production。

6)secret example-com-tls not found 或 tls: private key does not match public key。前者检查 Ingress 与 Secret 是否同命名空间、secretName 拼写;后者用模数比对:openssl x509 -noout -modulus -in fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5。不一致就重新签发,不要手工拼接。

7)续期后浏览器仍显示旧证书。执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller,并确认 Ingress 的 secretName 指向新 Secret;如果用了 CDN,还要刷新 CDN 证书或回源配置。

效果验证:从集群内到公网逐层确认

验证顺序应为 Secret → Ingress → 集群内 → 公网 → 客户端兼容性。先看对象:

kubectl get certificate -A
kubectl get secret example-com-tls -n production
kubectl describe ingress example-ingress -n production
kubectl get events -n production --sort-by=.lastTimestamp | tail -20

cert-manager 场景下 READY=True、Renewal Time 在未来;手动场景下 Secret 的 tls.crt 和 tls.key 都存在。然后核对 Ingress 的 TLS 段和 rules.host 是否一致,避免证书 SAN 不覆盖 www 子域。

集群内绕过 DNS 和外部 LB 验证:

kubectl run curl-test --rm -it --image=curlimages/curl --restart=Never -- curl -vk https://example.com --resolve example.com:443:10.0.0.10

把 10.0.0.10 换成 Ingress Controller Service 的 ClusterIP。输出中检查 subject、issuer、SSL certificate verify ok。公网验证:

curl -vI https://example.com
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

curl 不应出现 SSL certificate problem;openssl 输出应显示完整链和正确 SAN。再用浏览器开发者工具 Security 面板确认证书有效期和颁发者,最后用 SSL Labs 或 testssl.sh 检查 TLS 1.2/1.3、HSTS 和链。

最后做续期演练:cert-manager 可临时把 renewBefore 调大触发续期,观察 Certificate 事件和 Secret 更新时间;手动方案执行一次 acme.sh –renew –force,再跑 kubectl create secret 命令,确认 Ingress 重新加载。记录验证命令和预期输出,纳入监控告警,例如证书剩余天数小于 21 天时告警。这样才算完成 Let’s Encrypt 证书在 Kubernetes 的闭环部署。

常见问题

Let’s Encrypt 签发的 DV 证书有效期为 90 天,官方建议通过 ACME 客户端自动续期。cert-manager 默认在到期前约 30 天开始续期,可用 renewBefore 调整;手动部署的 Secret 需要重新创建并让 Ingress Controller 重新加载。

多命名空间、多团队、需要自动续期闭环时选 cert-manager;单集群少量域名且已有成熟发布流水线,可用 acme.sh 或 certbot 加 kubectl Secret,但必须配置 cron 续期、Secret 更新和 Ingress Controller reload,否则 90 天到期会中断。

通常是证书链不完整。Kubernetes Secret 的 tls.crt 必须使用 fullchain.pem,包含叶子证书和中间证书;只放 leaf 时浏览器可能自动补齐,但 curl、Java、Go、小程序会报 unable to get local issuer certificate 或 PKIX path building failed。

用模数比对:openssl x509 -noout -modulus -in fullchain.pem | openssl md5 和 openssl rsa -noout -modulus -in example.com.key | openssl md5,两行结果必须一致。不一致时 Kubernetes 会报 tls: private key does not match public key,应重新签发而不是手工拼接。

支持,但必须使用 DNS-01 校验,不能使用 HTTP-01。cert-manager 需要配置 DNS-01 solver 和 DNS 服务商凭据 Secret;acme.sh 则配置对应 DNS API。通配符证书适合多子域场景,但 DNS API 权限要最小化并妥善保管。

没有直接影响。Let’s Encrypt 证书有效期为 90 天,低于 398 天上限;398 天规则主要约束商业 CA 和公共信任 TLS 证书。使用企业 CA 或商业证书时,仍需确保单张证书有效期不超过 398 天,并提前规划续期。

内容审核

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