Concepts

Disponible

Fonctionnalité déployée et prise en charge. Les champs et commandes décrits ici sont stables au sein de la version v1alpha1.

Cinq notions suffisent pour utiliser StackNGO. Les pages suivantes les mettent en pratique.

Le tenant

Un tenant est votre espace sur la plateforme : un nom court (acme), un quota de ressources, un sous-domaine (acme.dev.stackngo.app), des permissions. Tout ce que vous déployez appartient à un tenant, et un tenant ne voit jamais les ressources d'un autre.

Vous pouvez avoir accès à plusieurs tenants (un par environnement, un par client, un par équipe). La CLI travaille toujours sur un tenant courant, choisi avec sng tenant use.

Le tenant ne s'écrit pas dans un manifeste

Le tenant d'une action est toujours celui de votre session. Vos manifestes ne le mentionnent donc jamais : ne précisez ni tenant ni emplacement dans metadata, la plateforme refuse un manifeste qui en déclare un. Pour agir sur un autre tenant, changez de session avec sng tenant use.

Identité et session

Deux jetons différents interviennent, et la CLI les gère pour vous :

1. Votre identité : obtenue par sng sso login auprès du service d'authentification (auth.dev.stackngo.app). Elle dit qui vous êtes.
2. Une session de tenant : obtenue par sng tenant use <tenant>. Elle dit sur quel tenant vous agissez et avec quelles permissions. Elle dure une heure et la CLI la renouvelle d'elle-même.

Les permissions sont des policies attachées à votre identité dans chaque tenant. Quand vous créez un tenant, vous en êtes administrateur. Vous pouvez ensuite donner des accès plus fins à d'autres personnes, à des machines ou à vos pipelines CI. Le détail est dans Identité et accès.

Manifestes et état désiré

Vous décrivez ce que vous voulez dans des fichiers YAML, les manifestes. Chaque manifeste a un kind (App, SSMSecret, DNSRecord, RegistryRepository, …) et un 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 envoie ce manifeste à la plateforme, qui le valide puis l'ajoute à l'état désiré de votre tenant. L'état désiré est l'ensemble des manifestes que vous avez appliqués : c'est la source de vérité, que vous pouvez relire (sng kind get App web), lister (sng kind list App), exporter (sng pull) ou supprimer (sng kind delete App web).

L'état désiré appartient à un tenant, sur un cluster. Pour tenir plusieurs environnements (acme-dev, acme-prod), créez un tenant par environnement.

Statut

Une fois un manifeste dans l'état désiré, la plateforme le met en œuvre, généralement en moins d'une minute : conteneurs, réseau, certificat, enregistrement DNS. Elle veille ensuite à ce que tout reste conforme à ce que vous avez décrit, et vous dit où elle en est dans le status de la ressource : des conditions (Ready, Progressing, Degraded) avec une raison courte (DomainNotAllowed, QuotaExceeded, …) et un message.

Lire le statut est le premier réflexe quand quelque chose ne se passe pas comme prévu :

sng app describe web

L'index des conditions liste toutes les raisons possibles et ce qu'il faut faire.

Les familles de ressources

Famille	Kinds	Ce que ça fait
Applications	App	Services, jobs et tâches planifiées, façon docker compose
Secrets	SSMSecret	Secrets versionnés, générés et tournés par la plateforme
Identité	IAMApplication, IAMRole, IAMGroup, IAMPolicy, IAMPolicyBinding, IAMOIDCTrust	SSO de vos applications, permissions, accès CI sans secret
Registre	RegistryRepository, RegistryAccessKey	Dépôts d'images privés et clés d'accès au registre
Sites statiques	CDNSite	Un site statique servi par le CDN
DNS	DNSZone, DNSRecord	Vos domaines et leurs enregistrements
Supervision	Monitor, NotificationChannel, StatusPage, MaintenanceWindow	Sondes d'uptime, alertes, page de statut
Infrastructure	Workspace, Provider	Modules OpenTofu appliqués depuis le tenant (à venir)

Le tableau complet, avec le statut de chaque kind, est dans la référence des manifestes.