Skip to main content

DNS records

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.

A DNS record publishes a name from your zones to an address, another name, a text or a mail server. You create it with sng dns record set or a DNSRecord manifest; the platform checks it, then publishes it within a few minutes.

Prerequisites​

  • A session on your tenant (sng tenant use acme).
  • The dns:write right to create or modify, dns:delete to delete (managed policies readwrite, admin). With readonly, you can list and describe.
  • For a brought domain: a declared zone. You can create the record before the zone: it is accepted, stays ZoneNotOwned, then is published on its own (Published) once the zone is proven. It is only published once the zone is Provisioned or Active.

1. Create a record​

NAME is relative to the zone: @ for the apex, www, a.b, *.preview, _dmarc. Without --zone, it is your default zone <tenant>.dev.stackngo.app.

# A in the default zone: www.acme.dev.stackngo.app
sng dns record set www --type A --target 203.0.113.10 --target 203.0.113.11

# MX at the apex of a brought domain
sng dns record set @ --zone exemple.fr --type MX --target "10 mx1.mail.ovh.net" --target "20 mx2.mail.ovh.net" --ttl 3600
enregistrement www.acme.dev.stackngo.app A créé : 203.0.113.10, 203.0.113.11 (id www-a-7c2e91d4)
effectif dans quelques minutes : sng dns record describe www-a-7c2e91d4

Keep the id: it is used by describe and delete. It is derived from the zone, the name and the type.

The same MX as a manifest:

mail.yml
apiVersion: dns.stackngo.io/v1alpha1
kind: DNSRecord
metadata:
  name: mail
spec:
  zone: exemple.fr           # absent: the tenant's default zone
  name: "@"                  # apex; must be quoted in YAML
  type: MX
  ttl: 3600
  targets: ["10 mx1.mail.ovh.net.", "20 mx2.mail.ovh.net."]
sng apply mail.yml

2. Choose the type and the targets​

TypeTarget (--target, repeatable)Rules
AIPv4 addresspublic address only
AAAAIPv6 addresspublic address only
CNAMEhostnamea single target, never at the apex (@)
TXTtext1 to 255 printable ASCII characters per target
MX"<priority> <host>"priority from 0 to 65535

For all: 1 to 16 targets, no duplicates; TTL from 60 to 86,400 s, 300 by default. Hostnames are written in lowercase; the trailing dot is tolerated.

Refused as addresses: private (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7), shared (100.64.0.0/10), loopback, link-local (including 169.254.169.254), multicast and unspecified.

sng dns record set db --type A --target 10.0.0.12
targets[0] : 10.0.0.12 n'est pas une adresse publique

3. Modify a record​

set is idempotent: a given zone + name + type triple is updated in place, targets and TTL replaced (not added). The message says mis à jour instead of créé.

sng dns record set www --type A --target 203.0.113.20

To change the name or the type, create the new record then delete the old one.

4. Delete a record​

sng dns record delete www-a-7c2e91d4
⚠ Suppression de l'enregistrement "www-a-7c2e91d4" (tenant "acme").
Tapez « oui » pour confirmer : oui
enregistrement www-a-7c2e91d4 supprimé

The record is removed from DNS within a few minutes. From a script: --yes. A record created by sng apply is deleted with its manifest name: sng dns record delete mail or sng kind delete DNSRecord mail.

Verification​

sng dns record describe www-a-7c2e91d4
id:       www-a-7c2e91d4
fqdn:     www.acme.dev.stackngo.app
zone:     acme.dev.stackngo.app (zone par défaut)
name:     www
type:     A
ttl:      300
targets:  203.0.113.20
ready:    yes
reason:   Published

ready: yes and Published: the record is published; it usually responds within a minute (dig +short www.acme.dev.stackngo.app). The other reasons:

reasonMeaningAction
Publishedpublished—
Conflictthe name is already held by another source (see below)free the name, or choose another one
Reservedname reserved for the platformchoose another name
ZoneNotOwnedthe zone is not (yet) declared and proven among your brought domains; the record is kept and published on its own as soon as it isdeclare the zone, or fix zone
ZoneNotReadythe zone is declared but not Provisioned yet; published automatically afterwardsfinish the verification
Invalidtarget or name refused (the message names the field)fix, sng apply

Without a reason and with synced: no: the platform has not seen the record yet. Wait a few minutes.

Conflicts​

A full name belongs to the first source that publishes it: a record, or the exposure of an App. The rule, per name:

  • two sources of the same type are in conflict (two TXT on _dmarc: put both values in the targets of a single record);
  • a CNAME is exclusive: no other type can coexist with it;
  • different types (A + TXT, A + MX) coexist without problems.

The loser switches to Conflict (message: <nom> <type> déjà publié par …) and is retried every minute: it is published as soon as the name is freed. An App exposed on shop.acme.dev.stackngo.app and a DNSRecord A on shop are in conflict: do not write a record for a name served by an App.

Within your tenant, the API also refuses to declare the same name and type twice, across all (409 enregistrement … déjà déclaré).

Going further​

  • Number of records: capped by the plan — 20 in 3XS, 50 in 2XS, 100 in XS, 200 in M, 400 in L, 800 in XL, 1,500 in 2XL, 2,000 in 3XL.
  • Wildcard: * (any first-level name) or *.preview are accepted; the * is only allowed at the start.
  • Length: name up to 200 characters, full name up to 253.
  • Machine output: --json on set, list, describe returns the API object (fields id, zone, default_zone, fqdn, ready, synced, reason, message…).
  • API: set maps to PUT /v1/dns/records (action dns:write, resource dnsrecord/<id>).

See also​