Concepts

Available

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

Five notions are enough to use StackNGO. The following pages put them into practice.

The tenant

A tenant is your space on the platform: a short name (acme), a resource quota, a subdomain (acme.dev.stackngo.app), permissions. Everything you deploy belongs to a tenant, and a tenant never sees another tenant's resources.

You can have access to several tenants (one per environment, one per customer, one per team). The CLI always works on one current tenant, chosen with sng tenant use.

The tenant is not written in a manifest

The tenant of an action is always the one from your session. Your manifests therefore never mention it: specify neither a tenant nor a location in metadata; the platform rejects a manifest that declares one. To act on another tenant, switch sessions with sng tenant use.

Identity and session

Two different tokens are involved, and the CLI manages them for you:

1. Your identity: obtained by sng sso login from the authentication service (auth.dev.stackngo.app). It says who you are.
2. A tenant session: obtained by sng tenant use <tenant>. It says which tenant you are acting on and with which permissions. It lasts one hour and the CLI renews it on its own.

Permissions are policies attached to your identity in each tenant. When you create a tenant, you are its administrator. You can then grant finer-grained access to other people, to machines or to your CI pipelines. The details are in Identity and access.

Manifests and desired state

You describe what you want in YAML files, the manifests. Each manifest has a kind (App, SSMSecret, DNSRecord, RegistryRepository, …) and a metadata.name.

web.yml

apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: web
spec:
  services:
    web:
      image: nginx:1.27
      ports: ["80"]
      ingress: {}

sng apply web.yml sends this manifest to the platform, which validates it and then adds it to the desired state of your tenant. The desired state is the set of manifests you have applied: it is the source of truth, which you can read back (sng kind get App web), list (sng kind list App), export (sng pull) or delete (sng kind delete App web).

The desired state belongs to a tenant, on a cluster. To keep several environments (acme-dev, acme-prod), create one tenant per environment.

Status

Once a manifest is in the desired state, the platform implements it, usually in less than a minute: containers, networking, certificate, DNS record. It then makes sure that everything stays consistent with what you described, and tells you where it stands in the status of the resource: conditions (Ready, Progressing, Degraded) with a short reason (DomainNotAllowed, QuotaExceeded, …) and a message.

Reading the status is the first reflex when something doesn't go as expected:

sng app describe web

The conditions index lists all possible reasons and what to do.

Resource families

Family	Kinds	What it does
Applications	App	Services, jobs and scheduled tasks, docker compose style
Secrets	SSMSecret	Versioned secrets, generated and rotated by the platform
Identity	IAMApplication, IAMRole, IAMGroup, IAMPolicy, IAMPolicyBinding, IAMOIDCTrust	SSO for your applications, permissions, secretless CI access
Registry	RegistryRepository, RegistryAccessKey	Private image repositories and registry access keys
Static sites	CDNSite	A static site served by the CDN
DNS	DNSZone, DNSRecord	Your domains and their records
Monitoring	Monitor, NotificationChannel, StatusPage, MaintenanceWindow	Uptime probes, alerts, status page
Infrastructure	Workspace, Provider	OpenTofu modules applied from the tenant (coming soon)

The complete table, with the status of each kind, is in the manifest reference.