密码学与证书 / 系统课时
排查 ACME 与 cert-manager 续期故障
排查 ACME 与 cert-manager 续期故障
cert-manager 续期失败要沿资源状态和 ACME 验证链路逐层定位,而不是反复删除 Secret。核心顺序是 Certificate → CertificateRequest → Order → Challenge → HTTP-01 或 DNS-01 验证 → 新证书写回 Secret,并结合控制器事件确认失败点。
学习目标
- 按 cert-manager 资源链定位自动续期停在哪个阶段。
- 检查 Order、Challenge、HTTP-01 或 DNS-01 验证及控制器事件。
- 判断 Secret 未更新是上游签发失败、验证失败还是写回后的消费问题。
先建立资源链而不是直接删 Secret
一个 Certificate 进入续期窗口后,cert-manager 会创建新的签发请求,再由 ACME Issuer 通过 Order 和 Challenge 完成域名控制权验证。真正的故障点可能在 Issuer 配置、ACME 账户、挑战传播、Ingress 路由、DNS 权限,或最后的 Secret 写入与工作负载重载。
先从目标 Certificate 开始,查看状态、条件、最近事件和相关 ACME 资源。
NS=apps
CERT=api-tls
kubectl -n "${NS}" describe certificate "${CERT}"
kubectl -n "${NS}" get certificaterequest,order,challenge
kubectl -n "${NS}" get events --sort-by=.lastTimestamp预期输出:正常证书应显示 Ready=True;续期中的证书可能暂时出现 Issuing=True。资源名、时间和原因均是动态值。
Status:
Conditions:
Type: Ready
Status: True
...
NAME READY AGE
certificaterequest.cert-manager.io/<ID> True <TIME>
沿 CertificateRequest、Order 和 Challenge 找到卡点
如果 Certificate 长时间处于 Issuing=True 或 Ready=False,不要只盯最外层状态。继续查看最新的 CertificateRequest、Order 和 Challenge,其中的 Reason、Message 和 Event 往往直接指出是等待 ACME 授权、验证失败还是账户或 Issuer 配置错误。
kubectl -n "${NS}" get certificaterequest -o wide
kubectl -n "${NS}" describe order <ORDER_NAME>
kubectl -n "${NS}" describe challenge <CHALLENGE_NAME>预期结果:健康流程中的 Order 最终应进入 valid;失败时 describe 会显示实际的状态、原因和错误消息。下面仅表示应关注的字段形态。
State: valid
Reason: <VALUE>
Message: <VALUE>如果连 Order 都没有生成,优先回看 CertificateRequest、Issuer/ClusterIssuer 的 Ready 条件和控制器事件;如果 Order 已存在但 Challenge 一直 pending,则把注意力转到域名验证路径。
分别验证 HTTP-01 与 DNS-01
HTTP-01 的关键是 ACME 服务器能够访问 http://<DOMAIN>/.well-known/acme-challenge/<TOKEN>。检查 solver 相关 Pod、Service 和 Ingress 是否存在,并从与 ACME 类似的外部网络视角请求该路径。
kubectl -n "${NS}" get pod,service,ingress -l acme.cert-manager.io/http01-solver=true
curl -i "http://<DOMAIN>/.well-known/acme-challenge/<TOKEN>"预期结果:路由正确时应返回 200,响应体包含当前 Challenge 对应的 key authorization;具体值由当前挑战决定。
HTTP/1.1 200 OK
...
<VALUE>DNS-01 则要验证 _acme-challenge.<DOMAIN> 的 TXT 记录是否已经出现在权威 DNS,而不是只看本机缓存解析器。
dig TXT "_acme-challenge.<DOMAIN>" +short
dig TXT "_acme-challenge.<DOMAIN>" @<AUTHORITATIVE_DNS_IP> +short预期输出:权威 DNS 应能看到当前挑战对应的 TXT 值;如果权威 DNS 没有记录,检查 DNS API 凭据、区域选择、委派关系和 solver 配置,再等待实际传播完成。
"<VALUE>"检查 Issuer、控制器和 Secret 写回
如果 Challenge 已经有效但证书仍未 Ready,检查 Issuer/ClusterIssuer、cert-manager 控制器日志和目标 Secret。日志应以资源名或域名为线索筛选,不要只看整个控制器最后几行。
kubectl describe clusterissuer <ISSUER_NAME>
kubectl -n cert-manager logs deploy/cert-manager --since=30m | grep -E "<DOMAIN>|${CERT}"
kubectl -n "${NS}" get secret <TLS_SECRET_NAME> -o jsonpath='{.type}{"\n"}{.metadata.resourceVersion}{"\n"}'预期输出:Issuer 应为 Ready;TLS Secret 的类型通常是 kubernetes.io/tls,重新签发并写回成功后 resourceVersion 会变化。
kubernetes.io/tls
<ID>若 Secret 已更新但入口仍提供旧证书,故障已经离开 ACME 签发链,应检查 Ingress Controller、Gateway、Sidecar 或应用是否监视该 Secret 并正确热加载。此时继续删除 Order 或 Challenge 只会制造新的噪声。
修复后主动触发并验证续期
修复配置、路由或 DNS 后,若环境安装了 cmctl,可以主动触发目标证书续期,用它验证整条自动化链路,而不是等待下一次自然续期窗口。
cmctl renew -n "${NS}" "${CERT}"
kubectl -n "${NS}" wait --for=condition=Ready certificate/"${CERT}" --timeout=300s预期结果:cmctl renew 应成功提交续期请求;随后 kubectl wait 在证书重新 Ready 后返回成功。资源名称会与实际 Certificate 一致。
certificate.cert-manager.io/<ID> condition met验收时再检查 Certificate 的 Not After 或 Secret 中叶子证书的到期时间是否向后推进,并从真实入口读取线上证书。这样可以确认“ACME 已签发、Secret 已写回、入口已加载”三个阶段全部恢复,而不是只看到某一个 Kubernetes 资源变绿。