Skip to main content

Exposure and domains

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

Add ingress to a service to make it reachable over HTTPS from the Internet. Without specifying anything, it responds at https://<service>-<app>.<tenant>.dev.stackngo.app/ with a certificate obtained automatically.

Prerequisites​

  • A service of kind deployment that declares at least one TCP port.
  • Nothing on the DNS side: your <tenant>.dev.stackngo.app zone is already served by the platform.

Steps​

1. Expose the service​

web.yml
apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: web
spec:
  services:
    web:
      image: nginxinc/nginx-unprivileged:1.27
      ports: ["8080"]
      ingress: { port: 8080 }            # https://web-web.<tenant>.dev.stackngo.app/
      healthcheck: { http: /, port: 8080 }
sng apply web.yml

On the command line: sng app create web --image nginxinc/nginx-unprivileged:1.27 --port 8080 --ingress (or --ingress=8080 to choose the port among several).

2. Wait for the certificate​

sng app describe web
App      : web
Statut   : prête
SERVICE  KIND        IMAGE                             PHASE  URL                                          DETAIL
web      deployment  nginxinc/nginx-unprivileged:1.27  Ready  https://web-web.<tenant>.dev.stackngo.app/  Reconciled 1/1 prêts

An exposed service is only Ready once its containers are ready and its HTTPS certificate is issued (usually less than a minute later). In between, it stays in Progressing with the reason CertificatePending:

SERVICE  KIND        IMAGE                             PHASE        URL                                          DETAIL
web      deployment  nginxinc/nginx-unprivileged:1.27  Progressing  https://web-web.<tenant>.dev.stackngo.app/  CertificatePending Le certificat HTTPS de l'App est en cours d'émission

When the service becomes Ready, its URL responds with a valid certificate. The services that depend on it (dependsOn) start without waiting for the certificate.

Verification​

curl -sI https://web-web.<tenant>.dev.stackngo.app/

HTTP/2 200, valid Let's Encrypt certificate.

The ingress fields​

FieldDefaultRole
portfirst TCP port in portsservice port that receives the traffic; must be in ports
path/path prefix served (/api serves /api and everything below it)
domain<service>-<app>.<tenant>.dev.stackngo.apphostname, among those you are allowed to use

An exposed service remains reachable by the other services of the App on its ports; from the Internet, only the ingress port is open.

Choose a hostname​

Your default zone​

Each tenant owns the zone <tenant>.dev.stackngo.app. You can choose any single-level name in it: shop.<tenant>.dev.stackngo.app, api-v2.<tenant>.dev.stackngo.app.

ingress: { port: 8080, domain: shop.<tenant>.dev.stackngo.app }

Replace <tenant> with the name of your tenant (sng config show). A name under another client's zone, or a platform domain, is refused at apply time:

Error: ingress.domain "…" : réservé à la plateforme ou à un autre client

Any other domain, yours, is declared as a brought domain.

Reserved names​

status.<tenant>.dev.stackngo.app is reserved for your status pages. A service that requests it switches to Failed, reason DomainNotAllowed (réservé à la plateforme (status pages)).

Your own domains​

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.

With brought domains, you will serve an App under a domain that belongs to you (www.exemple.fr, or the apex exemple.fr). You can declare the domain before its zone is ready: the service waits, then is published on its own. In this version, the rules also change for your default zone:

  • a name at any depth under <tenant>.dev.stackngo.app becomes allowed (a.b.<tenant>.dev.stackngo.app), the apex of the zone remaining excluded;
  • a brought domain can be used at its apex or below as soon as its zone is published (the certificate follows once the zone is Active);
  • a few technical names reserved for the operation of the platform (notably those that start with _) are refused everywhere, in addition to status.<default zone>.

The complete how-to: Domains on an App.

Automatic TLS​

Each exposed address receives a Let's Encrypt certificate, renewed by the platform. Nothing to configure. HTTP without TLS is not offered: the URL displayed in status is always https://.

Hostname conflicts (HostConflict)​

A hostname belongs to a single tenant, and within a tenant, a host + path pair belongs to a single App:

SituationResult
The same host is already served by another tenantservice Failed, HostConflict: le host … est déjà utilisé …
Another App of your tenant already serves this host on the same pathFailed, HostConflict: <host><path> est déjà servi …
Another App of your tenant serves this host on a different pathaccepted: two Apps can share a host by path
Two services of the same App on the same host and the same pathnot detected: which one responds is undefined; give them different path values
The name is already published in DNS by someone else (a DNSRecord of the same name, for example)service Failed, 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é

Fix: change the name of the service, of the App, the domain or the path, then sng apply. For DNSConflict, you can also free the name (delete the record that carries it): the service recovers on its own, without a new sng apply.

Remove the exposure​

Remove ingress from the manifest and apply, or sng app patch web --ingress-port 0. Within a minute, the address no longer responds and its certificate is removed.

Going further​

  • The hostname is compared in lowercase; write it in lowercase.
  • path is a prefix: /api captures /api/v1/users. To serve several services under the same host, give each one the same domain and a different path.
  • A job or cronjob service cannot be exposed (the schema rejects ingress).

See also​