跳到主要内容
Kubernetes

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 在云负载均衡终止,还需把新证书同步到云证书服务。

内容审核

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