DNSRecord

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.


`apiVersion`	`dns.stackngo.io/v1alpha1`
`kind`	`DNSRecord`
Appliqué par	`sng apply` (manifeste) ou `sng dns record set`
Commandes liées	`sng dns record list` · `describe` · `delete`, `sng template gen DNSRecord`

À quoi ça sert

Un DNSRecord publie un nom dans une zone que vous possédez : votre zone par défaut <tenant>.dev.stackngo.app, ou un domaine apporté par une DNSZone. Le nom est relatif à la zone, à toute profondeur. La plateforme vérifie que la zone est à vous, que le nom n'est pas réservé et qu'il n'est pas déjà publié ailleurs, puis l'envoie au fournisseur DNS. status.fqdn donne le nom complet.

Exemple minimal

www.yml
apiVersion: dns.stackngo.io/v1alpha1
kind: DNSRecord
metadata:
  name: www
spec:
  name: www                  # → www.<tenant>.dev.stackngo.app
  type: A
  targets: ["203.0.113.10"]

sng apply www.yml
sng dns record describe www

Équivalent sans manifeste : sng dns record set www --type A --target 203.0.113.10 (objet nommé www-a-<empreinte>).

Exemple complet commenté

dns.yml
apiVersion: dns.stackngo.io/v1alpha1
kind: DNSRecord
metadata:
  name: mail                 # nom d'objet libre ; sert d'id à sng dns record describe|delete
spec:
  zone: exemple.fr           # domaine d'une DNSZone de votre tenant ; absent = zone par défaut
  name: "@"                  # relatif à la zone : "@" (apex), "www", "a.b", "*.preview", "_dmarc"
  type: MX                   # A, AAAA, CNAME, TXT ou MX
  ttl: 3600                  # 60 à 86400 secondes ; 300 par défaut
  targets:                   # 1 à 16 cibles, sans doublon
    - "10 mx1.mail.ovh.net." # MX : "<priorité> <hôte>", point final toléré
    - "20 mx2.mail.ovh.net."
---
apiVersion: dns.stackngo.io/v1alpha1
kind: DNSRecord
metadata:
  name: dmarc
spec:
  zone: exemple.fr
  name: _dmarc
  type: TXT
  targets: ["v=DMARC1; p=quarantine; rua=mailto:dmarc@exemple.fr"]   # 255 caractères ASCII au plus
---
apiVersion: dns.stackngo.io/v1alpha1
kind: DNSRecord
metadata:
  name: preview-api
spec:
  name: api.preview          # zone par défaut : api.preview.<tenant>.dev.stackngo.app
  type: CNAME
  targets: ["my-api.netlify.app"]   # CNAME : une seule cible, jamais à l'apex

Champs

Règles de validation croisées

Le schéma refuse, dès sng apply :

un CNAME avec plusieurs cibles, ou à l'apex : un CNAME a une seule cible et n'est jamais à l'apex ;
un name hors du motif (minuscules, chiffres, -, _, * seulement en tête), un ttl hors de 60–86 400, plus de 16 cibles ou une cible de plus de 255 caractères.

L'API refuse en plus (et un manifeste qui passerait outre reste Invalid) :

une cible qui ne correspond pas au type : A = IPv4, AAAA = IPv6, CNAME = nom d'hôte en minuscules, TXT = texte ASCII imprimable, MX = "<priorité 0-65535> <hôte>" ;
une adresse non publique : privée, partagée (100.64.0.0/10), bouclage, link-local, multicast, non spécifiée ;
une cible en double ;
un nom réservé : tout label _acme-challenge, _stackngo-verify ou extdns-*, et dans la zone par défaut status et tout ce qui est dessous ;
dans un manifeste, zone égale à votre zone par défaut : zone "acme.dev.stackngo.app" : zone par défaut, laisser zone vide ;
une zone intrinsèquement invalide (sous-domaine, domaine de la plateforme, zone par défaut d'un autre client) (400) ; une zone apportée pas encore déclarée est acceptée : l'enregistrement reste ZoneNotOwned puis est publié tout seul quand la DNSZone est prouvée ; sans zone, l'enregistrement vise votre zone par défaut ;
le même couple zone + name + type déjà déclaré par un autre objet de votre tenant, tous contextes confondus (409).

sng apply et sng dns record set appliquent exactement les mêmes contrôles : déclarez la DNSZone avant ou après ses enregistrements.

DNSRecord

DNSRecord : enregistrement DNS de votre tenant, publié par la plateforme après contrôle de la zone.

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

DNSRecordSpec

DNSRecordSpec : un enregistrement DNS dans une zone que possède votre tenant.

Champ	Description	Défaut	Validation
`zone` string	Zone : domaine apporté par votre tenant (spec.domain d'une de vos DNSZone). Vide = zone par défaut de votre tenant, <tenant>.<domaine de base de la plateforme>.		MaxLength: 253 Pattern: `^([a-z0-9]([-a-z0-9]\{0,61\}[a-z0-9])?\.)+[a-z]([-a-z0-9]\{0,61\}[a-z0-9])?$` Optional: {}
`name` string	Name relatif à la zone, à toute profondeur : "@" (apex), "www", "a.b", "*.preview", "_dmarc".		MaxLength: 200 MinLength: 1 Pattern: `^(@\|\\|(\\.)?[a-z0-9_]([-a-z0-9_]\{0,61\}[a-z0-9])?(\.[a-z0-9_]([-a-z0-9_]\{0,61\}[a-z0-9])?)*)$`
`type` string	Type : A, AAAA, CNAME, TXT ou MX.		Enum: [A AAAA CNAME TXT MX]
`ttl` integer	TTL en secondes.	300	Maximum: 86400 Minimum: 60 Optional: {}
`targets` string array	Targets : IP (A, AAAA), nom d'hôte (CNAME), texte (TXT), "<priorité> <hôte>" (MX).		MaxItems: 16 MinItems: 1 items:MaxLength: 255

DNSRecordStatus

DNSRecordStatus : état de publication.

Champ	Description	Validation
`fqdn` string	FQDN publié (ou qui le serait).	Optional: {}
`observedGeneration` integer	Dernière version du manifeste prise en compte par la plateforme.	Optional: {}
`conditions` Condition array	Conditions de l'enregistrement (`Ready`…), avec leur `reason` et un `message` lisible.	Optional: {}

Statut et conditions

Une seule condition, Ready. status.fqdn est renseigné dès que la zone est connue, même si le nom n'est pas publié.

`reason`	`Ready`	Explication	Action
`Published`	`True`	l'enregistrement est envoyé au fournisseur DNS	—
`Conflict`	`False`	le nom est déjà tenu par une autre source : même type, ou un `CNAME` d'un côté ; le message cite le détenteur ; retenté chaque minute	supprimer l'autre source, ou choisir un autre nom
`Reserved`	`False`	nom réservé à la plateforme	choisir un autre nom
`ZoneNotOwned`	`False`	`la zone … n'appartient pas au tenant … : déclarer un DNSZone et prouver la propriété` ; état d'attente : l'enregistrement est conservé et publié tout seul (`Published`) dès que la zone est prouvée	créer la `DNSZone`, ou corriger `zone`
`ZoneNotReady`	`False`	`DNSZone … en phase Pending` (ou `Verified`) ; publication automatique une fois la zone prête	finir la vérification du domaine
`Invalid`	`False`	cible, nom ou longueur refusés (nom complet de plus de 253 caractères)	corriger, `sng apply`

Un enregistrement Conflict garde sa place dans la file : il est publié dès que le nom se libère. Tous les autres refus retirent l'enregistrement du DNS s'il y était.

Ce qui se passe à l'application

Création. L'enregistrement est publié en quelques minutes. Dans un domaine apporté, il est écrit dès que la zone est Provisioned, avant même la délégation : préparez vos enregistrements avant de changer les serveurs de noms.

Mise à jour. sng apply ou sng dns record set (même zone, nom et type) remplace cibles et TTL. Un changement de phase de la zone, ou sa suppression, réévalue tous les enregistrements du tenant.

Ce qui se passe quand vous supprimez

sng dns record delete <id> ou sng kind delete DNSRecord <nom> : l'enregistrement est retiré du DNS, au plus tard dans les 10 minutes. Aucune deletionPolicy.

Erreurs fréquentes

Symptôme	Cause	Correction
`un CNAME a une seule cible et n'est jamais à l'apex`	`CNAME` sur `@`	à l'apex, utilisez `A`/`AAAA`, ou exposez l'App sous l'apex (Domaines sur une App)
`targets[0] : 192.168.1.10 n'est pas une adresse publique`	adresse privée	utiliser l'adresse publique du service
`targets[0] : "mail.exemple.fr" : forme "<priorité> <hôte>" attendue`	`MX` sans priorité	`"10 mail.exemple.fr"`
`Conflict` : `shop.acme.dev.stackngo.app A déjà publié par ingress/…`	une App expose déjà ce nom	ne pas doubler une App par un enregistrement
`Conflict` entre deux `TXT` du même nom	deux objets pour le même nom et type	un seul objet, toutes les valeurs dans `targets`
`ZoneNotOwned`	la zone n'est pas (encore) déclarée et prouvée, a été retirée après coup, ou `zone` est mal orthographiée	`sng dns zone list` ; déclarer la `DNSZone` (publication automatique ensuite), ou corriger `zone`
`ZoneNotReady`	domaine apporté pas encore vérifié	Apporter un domaine
`status.acme.dev.stackngo.app : réservé aux status pages de la plateforme`	nom réservé	choisir un autre nom

Voir aussi

Guides : Enregistrements, Votre zone par défaut, Apporter un domaine.
CLI : sng dns record.
Autres kinds : DNSZone, App.

À quoi ça sert​

Exemple minimal​

Exemple complet commenté​

Champs​

Règles de validation croisées​

DNSRecord​

DNSRecordSpec​

DNSRecordStatus​

Statut et conditions​

Ce qui se passe à l'application​

Ce qui se passe quand vous supprimez​

Erreurs fréquentes​

Voir aussi​

À quoi ça sert

Exemple minimal

Exemple complet commenté

Champs

Règles de validation croisées

DNSRecord

DNSRecordSpec

DNSRecordStatus

Statut et conditions

Ce qui se passe à l'application

Ce qui se passe quand vous supprimez

Erreurs fréquentes

Voir aussi