DNSZone

Beta

Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.

Being enabled gradually on tenants.

apiVersion	dns.stackngo.io/v1alpha1
kind	DNSZone
Applied by	sng apply (manifest) or sng dns zone create
Related commands	sng dns zone list · describe · delete, sng template gen DNSZone

What it is for

A DNSZone hands StackNGO the DNS of a domain you bought elsewhere. The platform asks you to prove that the domain is yours (a TXT to add at its current DNS host), creates the zone at its provider, then gives you the name servers to declare at your registrar. Once the delegation is observed, the zone is Active: your DNSRecords and the ingress.domain of your Apps are published in it.

Minimal example

exemple-fr.yml

apiVersion: dns.stackngo.io/v1alpha1
kind: DNSZone
metadata:
  name: exemple.fr
spec:
  domain: exemple.fr

sng apply exemple-fr.yml
sng dns zone describe exemple.fr      # TXT to add, then name servers

Equivalent without a manifest: sng dns zone create exemple.fr (object named exemple.fr).

Complete annotated example

exemple-fr.yml

apiVersion: dns.stackngo.io/v1alpha1
kind: DNSZone
metadata:
  name: exemple.fr           # must equal spec.domain
spec:
  domain: exemple.fr         # registrable domain (not a subdomain), lowercase, no trailing dot; immutable
  source: Bring              # only accepted value: domain you bring (default)

The status is written by the platform only:

status:
  phase: Provisioned
  verification:
    name: _stackngo-verify.exemple.fr
    value: sng-verify-4b1f0e9c2a7d4e6b8c3f1a2d5e7b9c0f
  nameServers: [dns200.anycast.me, ns200.anycast.me]
  verifiedAt: "2026-10-07T09:41:12Z"
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "False"
      reason: AwaitingDelegation
      message: "déclarer chez le registrar les serveurs de noms : dns200.anycast.me, ns200.anycast.me"

Fields

Cross-field validation rules

The schema rejects, as early as sng apply:

• a spec.source other than Bring: l'achat de domaine (source: Purchase) n'est pas encore disponible;
• a change to spec.domain after creation: domain est immuable;
• a spec.domain outside the DNS pattern (lowercase, at least one dot, at most 253 characters).

The API also rejects, as early as sng apply or sng dns zone create:

• a non-registrable domain: subdomain (domaine "shop.exemple.fr" : sous-domaine de exemple.fr, déclarer exemple.fr) or unknown TLD;
• a StackNGO platform domain (stackngo.app, stackngo.fr), or anything below or above it;
• a domain already declared by another DNSZone in your tenant, across all contexts (409);
• any key other than name in metadata (tenant, labels, annotations).

After saving, the platform also checks that the domain is not already taken by another tenant (phase Rejected, reason Taken).

DNSZone

DNSZone : domaine apporté par votre tenant ; la plateforme en vérifie la propriété avant de publier le moindre enregistrement.

Champ	Description	Défaut	Validation
apiVersion string	dns.stackngo.io/v1alpha1
kind string	DNSZone
metadata ObjectMeta	Seul metadata.name est à renseigner (nom de la ressource dans votre tenant).
spec DNSZoneSpec
status DNSZoneStatus

DNSZoneSpec

DNSZoneSpec : un domaine dont votre tenant confie le DNS à StackNGO.

Champ	Description	Défaut	Validation
domain string	Domain : domaine enregistrable (ex. exemple.fr), jamais un sous-domaine ; immuable.		MaxLength: 253 Pattern: ^([a-z0-9]([-a-z0-9]\{0,61\}[a-z0-9])?\.)+[a-z]([-a-z0-9]\{0,61\}[a-z0-9])?$
source string	Source : Bring (domaine apporté). Purchase (achat du domaine via StackNGO) n'est pas encore disponible.	Bring	Enum: [Bring Purchase] Optional: {}

DNSZoneStatus

DNSZoneStatus : avancement de la prise en charge du domaine.

Champ	Description	Défaut	Validation
phase string	Phase : Pending (preuve de propriété attendue), Verified, Provisioned (délégation NS attendue), Active (enregistrements servis), Lost (délégation perdue) ou Rejected (domaine refusé).		Optional: {}
verification Verification	Verification : TXT à poser pour prouver la propriété (phase Pending).		Optional: {}
nameServers string array	NameServers : serveurs à déclarer chez le registrar du domaine.		Optional: {}
verifiedAt Time	VerifiedAt : date de la preuve de propriété.		Optional: {}
delegationLostAt Time	DelegationLostAt : premier constat d'une délégation absente après activation.		Optional: {}
observedGeneration integer	Dernière version du manifeste prise en compte par la plateforme.		Optional: {}
conditions Condition array	Conditions de la zone (Ready…), avec leur reason et un message lisible, par exemple l'attente de la délégation.		Optional: {}

Verification

Verification : enregistrement TXT à poser chez le DNS actuel du domaine.

Champ	Description	Défaut	Validation
name string	Name : nom complet de l'enregistrement TXT.
value string	Value : valeur attendue.

Status and conditions

Phase	Meaning	What you do
Pending	waiting for the proof of ownership; status.verification gives the TXT	add the TXT at the current DNS host
Verified	ownership proven (verifiedAt); the platform creates the zone	wait
Provisioned	zone created; status.nameServers filled in; your records are already written to it	declare the name servers at the registrar
Active	all the domain's public name servers are the zone's	nothing
Lost	delegation missing for more than 72 h; nothing is published anymore	add the TXT again, then restore the delegation
Rejected	domain refused; verification and nameServers cleared	fix or delete the zone

A single condition, Ready: True when the zone is Active (including during the grace period of a missing delegation).

reason	Phase	Ready	Explanation	Action
AwaitingVerification	Pending	False	TXT missing or different; read again every minute	add status.verification.name TXT status.verification.value
AwaitingProvisioning	Verified	False	zone not yet created at the provider; read again every 5 min	wait; support if it lasts more than one business day
ProviderError	Verified	False	the DNS provider did not respond	wait, automatic retry
AwaitingDelegation	Provisioned	False	public name servers differ from status.nameServers; read again every 5 min	declare all the servers in nameServers, and only those
DelegationCheckFailed	any phase after Verified	unchanged	the public lookup of the name servers failed	wait
Delegated	Active	True	delegation observed; checked again every hour	—
DelegationMissing	Active	True	delegation missing, for less than 72 h (delegationLostAt)	restore the name servers
DelegationLost	Lost	False	delegation missing for more than 72 h, or new proof expected	see Losing the delegation
NotRegistrable	Rejected	False	subdomain or unknown suffix; the message names the domain to declare	declare the registrable domain
PlatformDomain	Rejected	False	the domain overlaps a StackNGO domain	—
Taken	Rejected	False	le domaine … est déjà déclaré par un autre DNSZone (another tenant)	contact support if the domain is yours
Invalid	Rejected	False	source not available	remove source

A Rejected zone is re-evaluated: if the cause goes away (domain released by the other tenant, for example), it goes back to Pending.

What happens when you apply

Creation. The domain is reserved for your tenant, uniquely across the whole platform: no other customer can declare it. This reservation is tied to your tenant as it exists: a tenant deleted and recreated under the same name does not inherit the domain.

Update. spec.domain is immutable. An identical reapplication changes nothing.

What happens when you delete

sng dns zone delete exemple.fr or sng kind delete DNSZone exemple.fr. Both are refused (409, N enregistrement(s) utilisent encore la zone "exemple.fr", les supprimer d'abord) as long as DNSRecords of your tenant target the zone, across all contexts. Otherwise, the domain is released, no name in the domain is published anymore, and the Apps that use it go to DomainNotAllowed. Then hand the delegation back to your former DNS host. No deletionPolicy field.

Common errors

Symptom	Cause	Fix
sng dns zone create: domaine "www.exemple.fr" : sous-domaine de exemple.fr, déclarer exemple.fr	a subdomain was declared	declare exemple.fr; subdomains are managed with DNSRecord
sng dns zone create shows TXT de vérification pas encore calculé	the TXT was not ready after 20 seconds	sng dns zone describe exemple.fr a few moments later
Stays Pending, AwaitingVerification	TXT added in the wrong place (at the registrar while the DNS is hosted elsewhere), or doubled name (_stackngo-verify.exemple.fr.exemple.fr)	add the TXT at the host that serves the domain, name _stackngo-verify; dig +short TXT _stackngo-verify.exemple.fr @1.1.1.1
Stays Provisioned, AwaitingDelegation	an old name server was kept, or propagation is not finished	keep only the servers in nameServers; dig +short NS exemple.fr
Rejected, Taken	another tenant declared this domain	contact support with the proof of ownership
sng dns zone delete or sng kind delete DNSZone: 409 … enregistrement(s) utilisent encore la zone	DNSRecords target the zone	sng dns record list --zone exemple.fr, delete them
Active then Lost	domain expired, or name servers changed more than 72 h ago	renew the domain; add the TXT again, then restore the delegation

See also

• Guides: Bring a domain, Records, Domains on an App.
• CLI: sng dns, sng domain (purchase, upcoming).
• Other kinds: DNSRecord, App (ingress.domain).
• Security: Your domains belong to you.