Diagnose and fix cert-manager DNS01 propagation timeouts and CNAME delegation for ACME challenges

domain: cert-manager.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Run kubectl describe challenge <name> (and kubectl describe order) to confirm the failure is a DNS01 self-check/propagation issue rather than an ACME server-side or credentials problem.
  2. By default cert-manager self-checks using the recursive nameservers from /etc/resolv.conf inside the controller pod to discover the authoritative nameservers, then queries those directly; if the pod's resolver can't reach the authoritative NS (split-horizon DNS, restrictive egress), set the controller flags --dns01-recursive-nameservers=<HOST:PORT>,<HOST:PORT> (e.g. 8.8.8.8:53,1.1.1.1:53) and, if authoritative access is blocked entirely, add --dns01-recursive-nameservers-only=true so cert-manager only queries the configured resolvers.
  3. With the Helm chart, set these via extraArgs, e.g. --set 'extraArgs={--dns01-recursive-nameservers-only,--dns01-recursive-nameservers=8.8.8.8:53\,1.1.1.1:53}', then restart the cert-manager controller Deployment for the flags to take effect.
  4. If you don't want to grant cert-manager write access to the root zone, delegate the _acme-challenge subdomain: create _acme-challenge.example.com CNAME _acme-challenge.less-privileged.example.org, set cnameStrategy: Follow on the affected dns01 solver, and provide credentials scoped to less-privileged.example.org - cert-manager does not follow CNAMEs unless this is set.
  5. Use selector.dnsZones on the solver to scope which zones use the CNAME-delegated credentials versus root-zone credentials; the selector still matches against the original zone (example.com) even though the TXT record actually lands in the delegated zone.
  6. Re-trigger issuance (delete the stuck CertificateRequest/Order, or re-apply the Certificate) and re-check propagation; note that --dns01-recursive-nameservers-only can itself slow down the self-check due to resolver caching, so treat that as expected latency, not a new failure.

Known gotchas

Related routes

Configure a cert-manager ClusterIssuer with ACME DNS01 challenge using Route53 and create a wildcard certificate
cert-manager.io · 6 steps · unrated
Issue a TLS certificate via the ACME http-01 challenge (Let's Encrypt)
letsencrypt.org · 6 steps · unrated
Configure cert-manager DNS01 challenges with Route53 to issue a wildcard certificate
cert-manager.io · 5 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans