Bring a domain

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. Creating the zone after verification may take some time in this version.

You own exemple.fr at a registrar (OVH, Gandi, Namecheap…) and want to serve your Apps and your records there. You declare the domain, prove it is yours with a TXT record, then delegate its name servers to StackNGO.

Prerequisites

• The sng CLI authenticated, a session on your tenant (sng tenant use acme); sng config show displays the cluster and the tenant.
• The dns:write right (managed policies readwrite or admin).
• Access to the interface of your registrar and of the domain's current DNS host.
• A registrable domain: exemple.fr or exemple.co.uk, not shop.exemple.fr. StackNGO's own domains cannot be brought.
• Your plan must allow one more domain (see Going further).

1. Declare the domain

sng dns zone create exemple.fr

zone exemple.fr déclarée
étape suivante : posez cet enregistrement chez l'hébergeur DNS actuel du domaine :
  _stackngo-verify.exemple.fr  TXT  "sng-verify-4b1f0e9c2a7d4e6b8c3f1a2d5e7b9c0f"
puis suivez la vérification : sng dns zone describe <domaine>

The command waits a few seconds for the TXT value to be computed, then prints it. If it is still not ready after 20 seconds, the command says so (TXT de vérification pas encore calculé): sng dns zone describe exemple.fr will give it a few moments later. As a manifest:

exemple-fr.yml

apiVersion: dns.stackngo.io/v1alpha1
kind: DNSZone
metadata:
  name: exemple.fr
spec:
  domain: exemple.fr         # registrable domain, lowercase; immutable

sng apply exemple-fr.yml

A zone is always named after its domain (exemple.fr): sng dns zone create does it for you, and with sng apply the manifest's metadata.name must equal spec.domain. The two methods cannot declare the same domain. With sng apply, read the TXT afterwards with sng dns zone describe.

You can declare the zone before or after its records: a DNSRecord that targets a domain not declared yet is accepted, by sng apply as well as by sng dns record set. It stays ZoneNotOwned (nothing is published) until the zone is proven, then is published on its own.

2. Create the proof record

sng dns zone describe exemple.fr

domain:   exemple.fr
source:   Bring
phase:    Pending
ready:    no
reason:   AwaitingVerification
message:  poser chez le DNS actuel du domaine : _stackngo-verify.exemple.fr TXT "sng-verify-4b1f0e9c2a7d4e6b8c3f1a2d5e7b9c0f"

étape suivante : posez cet enregistrement chez l'hébergeur DNS actuel du domaine :
  _stackngo-verify.exemple.fr  TXT  "sng-verify-4b1f0e9c2a7d4e6b8c3f1a2d5e7b9c0f"
puis suivez la vérification : sng dns zone describe <domaine>

At the domain's current DNS host (often your registrar), create exactly this record: name _stackngo-verify, type TXT, the displayed value. The platform looks for it every minute from the Internet. As soon as it is seen, the zone switches to Verified.

After delegation

Once the zone is Active, the TXT created at the old host is no longer visible: this is normal, it is no longer needed. Note its value: it will be useful again if the delegation is ever lost (see Loss of delegation).

3. Wait for the zone to be created

In phase Verified, the platform creates your zone (reason AwaitingProvisioning). In this version, this creation is not immediate: allow some time, and contact support if the zone stays Verified beyond one business day.

The zone then switches to Provisioned and describe displays the name servers:

domain:   exemple.fr
source:   Bring
phase:    Provisioned
ready:    no
reason:   AwaitingDelegation
message:  déclarer chez le registrar les serveurs de noms : dns200.anycast.me, ns200.anycast.me

serveurs de noms à déclarer chez le registrar du domaine :
  dns200.anycast.me
  ns200.anycast.me

The server names above are examples: use the ones your zone displays.

4. Prepare your records before switching over

From Provisioned on, your records are written to the new zone, even if it is not served yet. Recreate there what you need before changing the name servers, to avoid an outage (email, third-party service verifications…):

sng dns record set @ --zone exemple.fr --type MX --target "10 mx1.mail.ovh.net" --target "20 mx2.mail.ovh.net" --ttl 3600
sng dns record set @ --zone exemple.fr --type TXT --target "v=spf1 include:mx.ovh.com ~all"

See Records.

5. Delegate at the registrar

At your registrar, replace the domain's name servers with those displayed by sng dns zone describe. The platform checks the delegation every 5 minutes; propagation depends on the registrar and on the TTL of the parent zone (from a few minutes to 48 hours).

Verification

sng dns zone list

DOMAIN      PHASE   READY  REASON
exemple.fr  Active  yes    Delegated

dig +short NS exemple.fr

The zone is Active when all the domain's public servers are those of the StackNGO zone. A partial delegation (an old server kept) stays AwaitingDelegation.

Loss of delegation

An active zone is checked every hour. If its name servers are no longer those of StackNGO (domain expired, resold, NS modified):

Duration	Phase	reason	Effect
less than 72 h	Active	DelegationMissing	nothing changes; ready stays yes
beyond 72 h	Lost	DelegationLost	no name in the zone is published anymore; services under this domain are no longer served and wait (WaitingForDNSZone)

To reactivate a Lost zone, prove ownership again, in this order:

1. create the _stackngo-verify TXT (same value, still displayed by describe) at the DNS host currently serving the domain;
2. wait for the zone to switch back to Provisioned;
3. declare the StackNGO name servers again at the registrar: the zone switches back to Active.

The proof is required because a lost domain may have changed owner. If you restore the StackNGO name servers first, the TXT can no longer be read (this name is reserved in your zone): go back temporarily to the old host, or contact support.

Remove a domain

sng dns zone delete exemple.fr

⚠ Retrait de la zone "exemple.fr" (tenant "acme").
Tapez « oui » pour confirmer : oui
zone exemple.fr supprimée

Removal is refused (409) as long as records use the zone (1 enregistrement(s) utilisent encore la zone "exemple.fr", les supprimer d'abord), whether you go through sng dns zone delete or sng kind delete DNSZone. Once the domain is removed, nothing is published under it anymore and it becomes free again for another tenant. Give the delegation back to your old host. From a script: --yes.

Going further

• Number of domains: capped by the tenant's plan — 1 in 3XS, 2 in 2XS, 3 in XS, 5 in M, 10 in L, 20 in XL, 30 in 2XL, 50 in 3XL. See Tenant and plans.
• One domain, one owner: a domain already brought by another tenant switches to Rejected, reason Taken. In your own tenant, the API refuses to declare the same domain twice (409).
• Domain refused: NotRegistrable (subdomain, unknown suffix) — the message indicates the domain to declare instead; PlatformDomain (StackNGO domain: stackngo.app, stackngo.fr, refused as soon as it is sent). The zone switches back to Pending on its own if the cause disappears.
• spec.domain is immutable: to change domains, delete the zone and create another one.
• Buy a domain: not offered yet (spec.source: Purchase is refused). See sng domain.
• Security: a brought domain can only be used by your tenant. See Security and privacy.

See also

• Records
• Domains on an App
• Reference: DNSZone, sng dns zone