Operations
How an issuance runs through DNS, how to choose between one certificate per host and a wildcard, how to delete and recover when a zone is no longer reachable, and the known limits.
How DNS-01 works
- The ACME order is created and the challenge token retrieved.
UPSERTof the_acme-challenge.<fqdn>TXT record in Route53, TTL 60.- Wait for
INSYNCon the Route53 ChangeId. - Then query the zone's authoritative name servers directly until all of them see the TXT. Not 8.8.8.8: a recursive resolver caches negative answers and will lie for the whole TTL.
- Notify the ACME server, validation, CSR finalization, download.
- Delete the TXT — including on failure (
finally). An orphan_acme-challengebreaks the next attempt.
Automatic renewal triggers at not_after - renew_before_days, with a deterministic jitter of ±24 h per certificate so that a whole fleet doesn't hit Let's Encrypt at the same hour.
Two possible strategies
| A — one cert per host | B — one wildcard | |
|---|---|---|
| Public A record pointing to the private IP | yes | no |
| Certificates | 1 per subdomain | shared *.home.example.com |
| LE rate limit | reached quickly beyond ~40 hosts | a single order |
| Internal topology exposed in public DNS | yes | no |
| Revocation | per host | all or nothing |
A is simpler and more granular. Switch to B beyond a few hosts, or if publishing your private IPs in a public zone bothers you. Both are supported: tick Wildcard in the console.
Deletion and recovery
The case that matters: the Route53 zone is no longer reachable (role revoked, zone deleted, expired credentials) and you still need to be able to clean up the database.
Nothing blocks on an external API error. Deleting a certificate revokes it with the CA on a best-effort basis and cleans up the zone on a best-effort basis: if either fails, the row is deleted anyway and whatever remains published is returned in warnings.
curl -X DELETE "https://certs.example.com/api/v1/certificates/$ID?purge=true" \
-H "Authorization: Bearer $TOKEN"{
"id": "cert_…",
"status": "deleted",
"warnings": [
"Could not remove A nas.home.example.com -> 192.168.1.50 from Route53: No hosted zone found with ID: ZINACCESSIBLE. The record is still published — delete it by hand."
]
}A domain cannot go away while a certificate references it. certificates.domain_id is ON DELETE RESTRICT: any remaining row pins the domain — revoked, failed or expired, not just active ones. The refusal is explicit and counted:
{
"type": "conflict",
"title": "Domain still has 3 certificate(s) (1 active). Delete them first, or repeat with ?force=true to remove them along with the domain.",
"detail": { "certificates": 3, "active": 1, "by_status": { "issued": 1, "failed": 1, "expired": 1 } }
}?force=true performs the cascade explicitly: best-effort CA revocation, best-effort zone cleanup, then deletion of the certificates and the domain in a single transaction. certificate_events and grants follow through SQL cascade.
curl -X DELETE "https://certs.example.com/api/admin/domains/$ID?force=true" -b cookies.txtIn the console, remove shows the count when refused and replaces the button with force (N). Records left in place in the zone are listed as a warning afterwards.
ACME server: good to know
The full description of the ACME endpoint is in ACME server. The operational points:
- The client signs the exact URL it calls. Behind a reverse proxy, either the proxy forwards
X-Forwarded-Proto/X-Forwarded-Host, or you setPUBLIC_URL. AJWS "url" is … but this endpoint is …error comes from there. - DNS validation takes one to three minutes; the client waits on its challenge during that time.
- These certificates appear in the console (
key_type: external) with no private key and no automatic renewal: the key stays with the client, which renews on its own.POST …/renewrefuses them. - ACME revocation (
revoke-cert): an account can revoke the certificates it obtained itself. - Not implemented:
keyChange(account key rollover) and revocation signed with the certificate's key.
Known limits
- All SANs in a single order must belong to a single managed zone.
- No Let's Encrypt rate-limit counter in the application: a large fleet can be refused by the CA. Worth adding if you go beyond ~40 certificates per week per registered domain.
- The PKCS#12 export format is not implemented (JSON and PEM only).
- Provenance markers double the number of records created in the zone (one TXT per name). That is the price of queryable ownership, given there are no tags on record sets;
TAG_RECORDS=0if you prefer a clean zone. - No
MASTER_KEYrotation: changing it makes already-stored private keys unreadable. A renewal regenerates them. - A single administrator account, created at setup. No multi-user management and no password change from the console — rotation goes through
scripts/reset-admin.ts.