docs/infrastructure/acme.md

ACME DNS Challenges

Summary

We agreed to use ACME DNS-01 challenges for issuing certificates for both public-facing and internal services. A key benefit is that DNS-01 enables internal certificate issuance in the first place, since the CA only needs to verify TXT records in DNS (no inbound HTTP/ALPN access to the service). To keep our primary DNS zones clean, we will create a separate, dedicated zone for ACME challenges and delegate challenge records to it via CNAME.

Decisions

• Use ACME DNS-01 as the challenge type for both external/public and internal certificate issuance.
• Create a dedicated DNS zone for ACME challenges (e.g., _acme.example.com).
• For each certificate FQDN, publish a CNAME at _acme-challenge.<fqdn> that points into the dedicated challenge zone.
• Store the TXT token(s) only in the dedicated challenge zone to avoid cluttering primary zones.
• Keep low TTLs (e.g., 60-120s) on both CNAME and TXT records to speed up renewals.
• Restrict write access to the challenge zone to the ACME automation only.

Reference Design

Dedicated zone:
_acme.example.com

For a service FQDN:
Target certificate: app1.example.com

Publish in the primary zone:

; Delegate the challenge to the dedicated zone
_acme-challenge.app1.example.com.  CNAME  app1._acme-challenge._acme.example.com.

Publish in the dedicated zone (managed by the ACME client/automation):

; ACME client writes the TXT token here
app1._acme-challenge._acme.example.com.  TXT  "ACME_VALIDATION_TOKEN"

During validation, the CA will follow the CNAME from the primary zone to the dedicated zone and read the TXT record there.