Skip to main content
4 video tutorials

Zones

A zone binds one or more DNS domains to a credential. Every name of a certificate that uses automated DNS-01 is validated through a zone the name is under — usually one zone for all names, or a zone per name when the names span several zones. CertAutoPilot uses that zone's credential to publish the name's _acme-challenge TXT record.

The zone model​

Each zone has:

  • Domains — one or more: example.com, internal.example, etc. A name is under the zone when it is under any of them.
  • Credential — one of the project's configured DNS credentials, used for every domain of the zone.
  • Optional name — how a zone with several domains is shown (for example Provincial governorates). Without a name the zone is shown by its first domain, followed by the number of other domains (ankara.gov.tr (+79)).
  • Optional description.

Zones are project-scoped, and a zone's credential must belong to the same project.

One zone for several domains​

When many domains are served by the same DNS account — 80 <il>.gov.tr domains in one provider account, say — add them to one zone instead of creating a zone per domain: under Settings → Zones → Add Zone, list the domains one per line. Names under any of these domains are validated through this zone's credential, and a certificate whose names are all under them needs only this zone.

  • A domain belongs to one zone of the project: adding a domain another zone already has is refused (409 ZONE_DOMAIN_TAKEN; the other zone is named only when you can see it). A longer domain is still a separate domain — example.com in one zone and internal.example.com in another is fine, and the longer one is suggested for the names under it.
  • Edit on the zone list changes the domains, the name, the credential and the description. A domain that a certificate's name is validated through cannot be removed (409 ZONE_DOMAIN_IN_USE, naming the certificates you can see and counting the others) — the next renewal would fail. Revoked and rejected certificates do not count. Only the credential fields you change are checked again, so renaming a zone does not contact the DNS server.
  • A credential pinned to one zone in its own settings (Route 53 hosted zone ID, Azure DNS zone name, Google Cloud DNS zone ID, DirectAdmin zone, Lightsail DNS zone, Windows DNS zone) can write that one DNS zone only; use a credential that can write every domain of the zone.
  • At most 1000 domains per zone.
  • Rolling upgrade: while a node older than 1.7.0 is running, saving a zone with more than one domain answers 409 CLUSTER_UPGRADE_REQUIRED — an older node checks names against the zone's first domain only.

Choosing the zone​

Every name of a certificate is validated through a zone the name is under — one of the zone's domains or a name below it. CertAutoPilot never picks the zone on its own when a certificate is created: the request names it, and the server only checks that each name is under the zone it was given.

The issue form suggests a zone for every name you type — the zone with the longest domain the name is under — and you can change it for a group of names or for one name. The API has the same suggestion at POST /zones/match; it is only a suggestion, the create request still carries the zones.

This is what lets different sub-trees of one apex use different providers: register them as separate zones and the longer one is suggested for the names under it.

ZoneCredentialSuggested for
example.comcloudflare-prodwww.example.com, api.example.com
internal.example.comroute53-internaldb.internal.example.com

Names in several zones​

One certificate can cover names that live in different zones — for example ankara.gov.tr, www.ankara.gov.tr, adana.gov.tr and www.adana.gov.tr, each its own zone, possibly with different DNS credentials or providers. Each name's challenge record is written and removed with the credential of its zone.

  • In the issue form, paste the names (one per line, or separated by commas or spaces). They are grouped by the zone suggested for each; a name no zone covers is marked and has to be given a zone (or the zone added under Settings → Zones) before you can continue. Add www. to apex names adds www.<name> for every name that is one of its zone's domains (not when *.<name> is already on the certificate — Let's Encrypt refuses a name a wildcard of the same order covers).
  • Through the API, send domain_zones — every name once, each with its zone_id. zone_id, when sent too, must be the zone of the first (primary) name. A request whose names all use one zone is stored exactly like a single-zone certificate.
  • A name and its wildcard (example.com and *.example.com) are validated by one DNS challenge, so they must use the same zone.
  • How the order is solved: a credential whose provider replaces the whole TXT record set (RFC 2136) writes one name at a time, so if any zone of the certificate uses one, every name is validated one after another, each waiting for DNS propagation — a long list takes a long time. A credential whose records are removed by the job that wrote them (Cloudflare, DigitalOcean, OVH, Plesk) makes the whole order run in one job instead of the phased flow. The form warns about both.
  • Every zone needs a DNS credential. A request whose names use several zones is refused at once when one of them has none (with a single zone the credential is only needed when the order runs). A credential that is pinned to one zone in its own settings (Route 53 hosted zone ID, Azure DNS zone name, Google Cloud DNS zone ID, DirectAdmin zone, Lightsail DNS zone, Windows DNS zone) can only write that zone — give each zone a credential that can write it.
  • Names, zones and their credentials are fixed when the certificate is created; renewals and re-issues use them again. To change them, create a new certificate.
  • GlobalSign Atlas certificates can use several zones too, with one difference: a name the Atlas account has already validated may have no zone, so domain_zones lists only the names that have one — see GlobalSign: names in several zones. The notes above about how an ACME order is solved do not apply to them.
  • Rolling upgrade: while a node older than 1.7.0 is running, creating a certificate whose names use more than one zone answers 409 CLUSTER_UPGRADE_REQUIRED. Once such certificates exist, do not start an older node again — it would write every name through the first zone's credential.
  • The zone's rate-limit counter records an issuance against the primary name's zone only.

Manual DNS needs no zone: the names can be in any zones, and the certificate page lists the records you create grouped by the CertAutoPilot zone they fall in (see Manual DNS).

CNAME aliasing​

Common pattern when the production zone is locked down (regulated, or owned by another team): publish a CNAME at _acme-challenge.api.example.com pointing to _acme-challenge.api.acme.example.org, where acme.example.org is a zone CertAutoPilot can write to. The CA follows the CNAME and validates the record where it lives.

; Once, manually, in the production zone:
_acme-challenge.api.example.com. CNAME _acme-challenge.api.acme.example.org.

No configuration is needed in CertAutoPilot — there is no "challenge override" field. The challenge record name is resolved through the CNAME automatically, so the record is written in the delegated zone. The certificate's name must still be under the zone it uses, so register a zone for the name's own domain (example.com, or api.example.com) and give it a credential that can write the delegated zone (acme.example.org); select that zone on the certificate.

What is checked on save​

Creating or editing a zone validates:

  1. Every domain is a valid DNS name — labels of letters, digits, hyphens and underscores, at most 63 characters each and 253 in all, no wildcard. Domains are stored lower-case, without a trailing dot, an internationalised domain in its xn-- form; a domain listed twice is kept once.
  2. No domain belongs to another zone of the project (409 ZONE_DOMAIN_TAKEN).
  3. The selected DNS credential exists and belongs to the same project.
  4. For a Windows DNS (WinRM) credential only: every domain must be equal to or under the credential's configured DNS Zone, otherwise the request is rejected (400). The check is best-effort — if the credential's stored config cannot be decrypted it does not block, and the issuance-time check still guards.

The domain format is not otherwise constrained: there is no Public Suffix List enforcement, so registering a public-suffix name is not blocked.

No probe record is written on save. To verify that the credential can actually create records, use the credential's Test button with a domain — that writes and immediately deletes a throw-away TXT record. See DNS providers.

API​

GET /api/v1/projects/{project}/zones
POST /api/v1/projects/{project}/zones (project admin)
POST /api/v1/projects/{project}/zones/match (suggests a zone per name)
GET /api/v1/projects/{project}/zones/{id}
PATCH /api/v1/projects/{project}/zones/{id} (project admin)
DELETE /api/v1/projects/{project}/zones/{id} (project admin)
GET /api/v1/projects/{project}/zones/{id}/certificates
GET /api/v1/projects/{project}/zones/{id}/rate-limits

POST takes domains (a list) or domain (one), dns_credential_id, and optional name and description. PATCH takes any of domains (replaces the whole list), name (an empty string removes it), dns_credential_id and description. A zone in a response carries domain (its first domain, kept for older clients) and domains (all of them).

A zone cannot be deleted while a certificate validates any of its names through it — as its zone or as the zone of one of its names. The zone's certificate list and the credential's usage list count those certificates too.

POST /zones/match takes {"domains": [...]} (at most 1000) and answers, for each name in order (and truncated when the project has more than 10,000 zones), the zone with the longest domain the name is under among the zones you can see — with zone_domain (the zone's domain the name is under), zone_label (how the zone is shown), has_credential, the credential's provider type (and its name when you can see the credential), sequential (RFC 2136), in_process_cleanup, and apex (the name is one of the zone's domains). A name no zone covers has no zone_id; an invalid name answers with error.

See also​

Video tutorials

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Get Started — First Admin, Let’s Encrypt and Google Cloud DNSYouTube ↗
Domain Monitoring (WHOIS, DNS Health) and CA Rate LimitsYouTube ↗
One Certificate Across Several DNS ZonesYouTube ↗
One Zone for Several Domains Behind One DNS AccountYouTube ↗