Écrire une policy

Disponible

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

Une policy dit qui peut faire quoi dans votre tenant : un document JSON court, inspiré des policies IAM des fournisseurs de cloud, que vous attachez ensuite à des utilisateurs, des rôles ou des machines. Chaque tenant naît avec quatre policies gérées à votre disposition (assume-role, readonly, readwrite, admin) ; vous écrivez les vôtres pour affiner.

ops-read.json
{ "Version": "1",
  "Statement": [
    { "Effect": "Allow", "Actions": ["ssm:read", "ssm:list", "ssm:describe"], "Resources": ["secret/*"] },
    { "Effect": "Deny",  "Actions": ["ssm:read"], "Resources": ["secret/prod-*"] } ] }

sng tenant policy create ops-read -f ops-read.json --description "lecture des secrets hors production"

policy "ops-read" created (pending: applied in a few minutes)

Prérequis

Une session sur le tenant : sng tenant use acme (Le modèle).
L'action policy:admin sur policy/<nom> : la policy gérée admin l'inclut, readwrite non (écrire des policies est une élévation de privilèges).

Le document

{
  "Version": "1",
  "Statement": [
    { "Effect": "Allow", "Actions": ["<action>", "..."], "Resources": ["<ressource>", "..."] }
  ]
}

Clé	Valeur	Règle
`Version`	`"1"`	seule version acceptée
`Statement`	tableau	1 à 50 entrées
`Effect`	`Allow` ou `Deny`	respect de la casse
`Actions`	tableau	1 à 64 motifs d'action
`Resources`	tableau	0 à 64 motifs ; absent ou vide = `["*"]`

La validation est stricte : une clé inconnue, un effet, une action ou une ressource mal formés donnent 400. Ainsi une faute de frappe dans un Deny ne peut pas le désactiver en silence. Un document pèse au plus 64 Kio.

Actions

Une action s'écrit service:verbe (insensible à la casse, normalisée en minuscules) ou est une méthode HTTP.

Famille	Valeurs	Joker
Services	`ssm:`, `iam:`, `deploy:`, `env:`, `policy:`, `kms:`, `cdn:`, `tier:`, `registry:`, `oidctrust:`	`*:verbe`
Verbes	`read`, `list`, `describe`, `write`, `delete`, `rotate`, `declare`, `admin`, `wrap`, `unwrap`, `rewrap`, `assumerole`, `upload`, `purge`, `logs`, `pull`, `push`	`service:*`
Méthodes HTTP (API générées de vos applications)	`GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`	aucun
Tout	`*`	couvre les deux familles

Les verbes de service et les méthodes HTTP sont deux familles distinctes : *:* ne couvre pas GET. Seul * couvre tout. Le service dns s'ajoute à cette liste là où la gestion DNS est activée.

Ressources

Forme	Exemple	Joker
Tout	`*`	—
Logique `type/nom`	`secret/db-password`, `app/api`, `tenant/acme`	`` en suffixe* seulement : `secret/`, `secret/prod-`, `resource/deploy/*`
Chemin (tout hôte du tenant)	`/v1/orders/*`	`` = un segment en milieu de chemin ; `` final = tout le sous-arbre
URL complète	`https://orders-api.acme.dev.stackngo.app/v1/orders/*`	idem, hôte exact

Types logiques connus : secret, resource, release, env, tenant, user, role, group, app, policy, key, cdn, tier, repository, oidctrust (plus dnszone, dnsrecord avec le DNS). Le catalogue des actions donne la ressource exacte de chaque route.

Évaluation

Pour une action sur une ressource, StackNGO lit toutes les policies attachées à votre sujet (vous et vos rôles, ou l'application machine, ou le job CI) dans le tenant de la session :

Deny explicite qui correspond → refus ;
sinon premier Allow qui correspond → accord ;
sinon → refus.

Une opération sur toute une collection (lister les secrets, créer une app) vérifie la forme type/* : un Allow secret/* la couvre ; un Deny secret/prod-* ne la bloque pas (le service filtre ensuite élément par élément).

Les policies gérées

Chaque tenant possède des policies gérées : créées à la création du tenant, non modifiables, non supprimables. Leurs noms sont réservés : sng tenant policy create admin répond 409. Vous pouvez en revanche les attacher à qui vous voulez.

Nom	Statements exacts	Attachée par défaut à
`assume-role`	`Allow` `iam:assumerole` sur `tenant/<tenant>`	le créateur du tenant, et la plateforme pour l'administration de votre tenant
`readonly`	`Allow` `:read`, `:list`, `:describe`, `deploy:logs`, `registry:pull`, `GET`, `HEAD` sur ``	personne
`readwrite`	`Allow` tout `readonly` + `ssm:write`, `ssm:delete`, `ssm:rotate`, `ssm:declare`, `deploy:write`, `deploy:delete`, `env:write`, `cdn:write`, `cdn:delete`, `cdn:upload`, `cdn:purge`, `registry:push`, `registry:delete`, `POST`, `PUT`, `PATCH`, `DELETE` sur `*`	personne
`admin`	`Allow` `` sur ``	le créateur du tenant, et la plateforme pour l'administration de votre tenant

Deux autres policies gérées, réservées à la plateforme, lui permettent de déclarer et de faire tourner vos secrets ; elles n'accordent jamais l'écriture d'une valeur. Elles apparaissent dans sng tenant policy list : ne les attachez à personne.

À retenir :

readonly et readwrite n'incluent pas iam:assumerole : pour qu'un utilisateur entre dans le tenant, attachez-lui aussi assume-role (--with-assume).
readwrite n'inclut ni policy:* ni tier:write ni auth:ReadCredentials : gérer les policies et le tier, ou lire les identifiants d'une application, demande admin.

Gérer vos policies

Lister

sng tenant policy list

NAME         DEFAULT  STATUS   VERSION  DESCRIPTION
admin        yes      applied  1        Accès complet au tenant, y compris la gestion des utilisateurs, des rôles et des policies.
assume-role  yes      applied  1        Permet d'ouvrir une session sur ce tenant.
ops-read              pending           lecture des secrets hors production
readonly     yes      applied  1        Lecture seule : consulter les ressources du tenant sans rien modifier.
readwrite    yes      applied  1        Lecture et écriture des ressources du tenant (secrets, déploiements, sites, images), sans gestion des accès.
…

Chaque policy gérée porte une description qui dit à quoi elle sert. La liste se termine par les deux policies gérées réservées à la plateforme : leur description commence par « Réservée à la plateforme » et se termine par « Ne pas attacher ».

Statut	Signification
`applied`	le document demandé est celui en vigueur
`pending`	créé ou modifié, pas encore en vigueur (quelques minutes)
`deleting`	suppression demandée, policy encore en vigueur quelques minutes

Lire

sng tenant policy get ops-read          # le document JSON
sng tenant policy get ops-read --json   # avec name, description, default, status, version, document

Créer et remplacer

sng tenant policy create NAME -f FILE [--description TEXTE]
sng tenant policy update NAME -f FILE [--description TEXTE]

create refuse une policy qui existe déjà ; update refuse une policy absente.
-f accepte un document JSON ou YAML, la sortie de policy get --json, ou un manifeste IAMPolicy (-f - lit l'entrée standard). Avec un manifeste, spec.description sert de description.
Le nom est un label DNS (minuscules, chiffres, -, 63 caractères au plus), ni réservé, ni préfixé bind-.

Équivalent déclaratif de l'exemple d'ouverture :

ops-read.yml
apiVersion: iam.stackngo.io/v1alpha1
kind: IAMPolicy
metadata:
  name: ops-read
spec:
  description: lecture des secrets hors production
  statement:
    - effect: Allow
      actions: ["ssm:read", "ssm:list", "ssm:describe"]
      resources: ["secret/*"]
    - effect: Deny
      actions: ["ssm:read"]
      resources: ["secret/prod-*"]

sng tenant policy create ops-read -f ops-read.yml

Pas de sng apply pour les policies

Les kinds IAMPolicy et IAMPolicyBinding passent par sng tenant policy, pas par sng apply : l'API les enregistre elle-même dans l'état désiré de votre tenant après validation. Voir la Référence des manifestes.

Supprimer

sng tenant policy delete ops-read --yes

policy "ops-read" deletion requested (applied in a few minutes)

La suppression retire aussi tous ses attachements. Les policies gérées ne se suppriment pas (409).

Vérification

Après une à quelques minutes :

sng tenant policy list
sng tenant policy principals ops-read

Le statut passe de pending à applied, et principals affiche les sujets réellement attachés (applied) face aux sujets demandés (requested).

Pour aller plus loin

409 policies_pending : à la création d'un tenant, ses policies gérées mettent quelques minutes à s'appliquer. Pendant ce délai (5 min au plus), ouvrir une session répond 409 policies_pending avec Retry-After: 10 ; sng tenant use attend tout seul.
Cycle d'écriture : sng tenant policy … appelle PUT /v1/iam/policies/<nom>, qui valide le document et répond 202 Accepted ; la policy passe pending, puis applied en quelques minutes. Le binding d'une policy s'appelle toujours bind-<policy>.
Verrou optimiste : chaque application incrémente version. sng tenant policy list l'affiche.

Policy pour une API générée : les méthodes HTTP visent les routes de vos propres applications exposées sous <service>-<app>.<tenant>.dev.stackngo.app :

{ "Version": "1", "Statement": [
  { "Effect": "Allow", "Actions": ["GET"], "Resources": ["https://orders-api.acme.dev.stackngo.app/v1/orders/*"] } ] }

Policy pour une CI qui publie un site sans pouvoir le créer ni le supprimer :

{ "Version": "1", "Statement": [
  { "Effect": "Allow", "Actions": ["cdn:upload", "cdn:purge"], "Resources": ["cdn/*"] },
  { "Effect": "Deny",  "Actions": ["cdn:*"], "Resources": ["cdn/prod-*"] } ] }

Prérequis​

Le document​

Actions​

Ressources​

Évaluation​

Les policies gérées​

Gérer vos policies​

Lister​

Lire​

Créer et remplacer​

Supprimer​

Vérification​

Pour aller plus loin​

Voir aussi​