Domains on an App

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.

Multi-level names and brought domains are being enabled gradually on tenants.

The ingress.domain field of a service chooses the hostname under which it responds over HTTPS. The platform publishes this name in DNS and obtains its certificate: you write neither a record nor a TLS configuration.

Prerequisites

• An App with an exposed service (ingress). See Exposure and domains.
• For a domain of your own: nothing to do before deployment. You can declare the domain while its verification is not finished: the service waits, then is published on its own (Bring a domain). The certificate is only obtained once the zone is Active, that is, once the name servers are declared at your registrar.

1. A name in your default zone

Any name under <tenant>.dev.stackngo.app, at any depth:

shop.yml

apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: shop
spec:
  services:
    web:
      image: registry.gitlab.com/acme/shop-web:2.1.0
      ports: ["8080"]
      ingress:
        port: 8080
        domain: www.shop.acme.dev.stackngo.app    # two levels under the zone: accepted

sng apply shop.yml

The apex acme.dev.stackngo.app itself is refused, as are the reserved names.

2. A brought domain

The apex and any name below it can be used. You can declare exemple.fr before its zone is ready: the service waits, then is served without a new command. The order of your sng apply commands does not matter.

shop.yml

apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: shop
spec:
  services:
    web:
      image: registry.gitlab.com/acme/shop-web:2.1.0
      ports: ["8080"]
      ingress: { port: 8080, domain: exemple.fr }         # apex of the brought domain
    api:
      image: registry.gitlab.com/acme/shop-api:2.1.0
      ports: ["8080"]
      ingress: { port: 8080, domain: api.exemple.fr }

sng apply shop.yml

To serve the apex and www, declare two services, or expose the App under the apex and add a www CNAME to this name:

sng dns record set www --zone exemple.fr --type CNAME --target exemple.fr

On the command line, sng app create does not take a domain: sng app create shop --image … --port 8080 --ingress exposes under the default name; then add domain to the manifest (sng kind edit App shop, or your file then sng apply).

3. Wait for publication and the certificate

sng app describe shop

App      : shop
Statut   : prête
SERVICE  KIND        IMAGE                                     PHASE  URL                        DETAIL
api      deployment  registry.gitlab.com/acme/shop-api:2.1.0   Ready  https://api.exemple.fr/    Reconciled 1/1 prêts
web      deployment  registry.gitlab.com/acme/shop-web:2.1.0   Ready  https://exemple.fr/        Reconciled 1/1 prêts

As long as the zone of the domain is not ready, the service is in phase Waiting with the reason WaitingForDNSZone. The message says what is missing, and the name is not served while it waits:

Message	What is missing	What to do
en attente de la zone DNS du domaine <nom> : aucune zone déclarée ne le couvre	the domain is not declared yet	Bring a domain
en attente de la zone DNS <zone> (état Pending) : preuve de propriété du domaine attendue	the verification TXT record	add the record at your registrar
en attente de la zone DNS <zone> (état Verified) : création de la zone en cours	the zone is being created	wait
en attente de la zone DNS <zone> (état Lost ou Rejected) : la zone doit être rétablie	the zone was lost or rejected	reactivate the zone

As soon as the zone is ready, the name is published and the service becomes Ready, without a new command. A Provisioned zone publishes the name; the certificate is validated through DNS and only issued once the delegation is effective (zone Active). In between, the service stays in Progressing with the reason CertificatePending (message: certificat en attente : la délégation des serveurs de noms de <zone> n'est pas encore constatée); it becomes Ready when the certificate is issued.

Verification

dig +short api.exemple.fr
curl -sI https://api.exemple.fr/

An address in response, then HTTP/2 200 with a valid Let's Encrypt certificate.

Refusals and errors

Situation	When	Message or reason
domain of another client's zone, or platform domain	sng apply	ingress.domain "…" : réservé à la plateforme ou à un autre client
apex of the default zone	sng apply	ingress.domain "acme.dev.stackngo.app" : apex de la zone du tenant, choisir un nom dessous
reserved name (_acme-challenge, _stackngo-verify, extdns-*)	sng apply	ingress.domain "…" : label "…" réservé à la plateforme
status.<tenant>.dev.stackngo.app	sng apply	ingress.domain "…" : réservé aux status pages de la plateforme
platform domain (stackngo.fr, stackngo.app) declared in an App	service status	Failed, DomainNotAllowed (final refusal)
brought domain whose zone is not ready yet, or zone Lost	service status	Waiting, WaitingForDNSZone (waiting, see above)
name served by another tenant or another App on the same path	service status	Failed, HostConflict
name already published by a record (DNSRecord)	service status	Failed, DNSConflict
certificate not issued yet	service status	Progressing, CertificatePending

Name already taken by a record

If a record (DNSRecord) already publishes the same name (type A, AAAA or CNAME), first come keeps the name: the App is deployed but its name is not published, and the service becomes Failed with the reason DNSConflict (Le nom de domaine … est déjà utilisé : l'App n'est pas joignable à cette adresse tant qu'il n'est pas libéré). Delete the record: the App's name is published within a minute and the service recovers.

Going further

• A zone that switches to Lost withdraws the publication of all its names. Services that depend on it are no longer served: they switch to waiting (Waiting, WaitingForDNSZone) until reactivation, then resume on their own.
• A brought domain is shared by path between several Apps of the tenant, like a name in the default zone: same domain, different path values.
• Publication follows exposure: removing ingress (or deleting the App) removes the name from DNS.
• Static sites (CDNSite) do not accept a brought domain yet, only the default zone: see Publish a site.

See also

• Exposure and domains
• Bring a domain, Records
• Reference: App and DNSZone
• Security and privacy