Déclarer un secret par manifeste

Disponible

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

Avec un manifeste SSMSecret, le secret fait partie de la description de votre tenant, comme vos Apps : il est créé quand le manifeste est appliqué, sa rotation est déclarée dans la spec, et il est supprimé avec le manifeste. La valeur, elle, ne passe jamais par Git : la plateforme la génère, ou vous la posez avec sng secret set.

Prérequis

• La CLI configurée pour appliquer des manifestes : cluster et tenant choisis (sng config use-cluster, sng tenant use). Voir Le cycle validate, plan, apply.
• Le droit d'appliquer des manifestes dans votre tenant (policy readwrite ou admin).
• Aucun droit particulier sur les secrets n'est nécessaire pour déclarer : la plateforme crée le secret pour vous. Pour lire la valeur générée, il vous faut ssm:read.

1. Déclarer un secret à valeur générée

sng secret create db-password --length 24 --rotation 30

secret "db-password" declared in tenant acme-dev: …

acme-dev est le tenant courant de votre configuration sng. La commande a produit un manifeste et l'a appliqué, exactement comme sng apply :

db-password.yml

apiVersion: ssm.stackngo.io/v1alpha1
kind: SSMSecret
metadata:
  name: db-password
spec:
  length: 24
  rotateDays: 30

Pour l'écrire vous-même et le garder dans votre dépôt, ajoutez --dry-run : le manifeste est imprimé sans être appliqué.

sng secret create db-password --length 24 --rotation 30 --dry-run > secrets/db-password.yml
sng apply secrets/db-password.yml

sng template gen SSMSecret db-password produit le même squelette, commenté.

En moins d'une minute après l'application, le secret a une valeur :

sng secret describe db-password

{
  "name": "db-password",
  "keys": ["value"],
  "version_id": "1",
  "rotation_enabled": true,
  "rotation_days": 30,
  "next_rotation_date": "2026-11-06T10:02:17Z",
  "version_stages": { "current": "1" }
}

2. Déclarer un secret dont vous posez la valeur

Quand la valeur vient d'ailleurs (clé d'API d'un fournisseur, mot de passe d'un service externe), déclarez le secret vide avec --length 0, puis posez la valeur :

sng secret create smtp-password --length 0 --description "Mot de passe SMTP Mailjet"

secret "smtp-password" declared in tenant acme-dev: …
set its value with: sng secret set smtp-password

sng secret set smtp-password --from-file ./smtp-password

Tant que la valeur n'est pas posée, le secret existe mais est en attente : une App qui le référence ne démarre pas ce service (voir Injecter un secret dans une App). Dès le set, il devient actif ; le statut du manifeste suit dans les 10 minutes.

3. Choisir la forme de la valeur générée

sng secret create api-key --length 40 --contains letters,numbers

Flag	Rôle	Défaut
--length N	longueur de la valeur générée ; 0 = déclaré vide	16
--rotation N	renouvellement tous les N jours ; 0 = jamais ; exige --length > 0	0
--contains	classes : letters, numbers, symbols (alias letter, alpha, number, digit, symbol, punctuation) ; exige --length > 0	toutes
--description	texte libre, visible dans sng secret describe	vide
--dry-run	imprime le manifeste sans l'appliquer	—

Le vocabulaire du manifeste est volontairement plus simple que celui de sng secret set : pas de lower/upper séparés, pas d'--exclude-chars. Si vous avez besoin de ces réglages, posez la valeur avec set (--length 0 dans le manifeste), ou armez la rotation avec set --rotation plutôt qu'avec rotateDays.

4. Ce qui n'est jamais écrasé

Le manifeste décrit comment produire une valeur, pas la valeur. Conséquences :

• Réappliquer le manifeste ne change jamais une valeur existante, pas plus que les vérifications régulières de la plateforme.
• Si vous aviez déjà fait sng secret set db-password avant de déclarer le secret, la déclaration adopte cette valeur et ne la régénère pas.
• Modifier length ou contains après coup ne change pas la valeur courante : seules la première génération et les rotations futures en tiennent compte. Pour changer la valeur maintenant : sng secret rotate db-password --length 40.
• rotateDays est la seule chose qui remplace la valeur, et il le fait quelle que soit son origine. Ne mettez pas rotateDays sur un secret dont la valeur vient d'un service externe.

5. Rendre le secret utilisable par un site statique ou un canal de notification

Par défaut, un secret n'est mis à disposition que des Apps qui le référencent. Un site statique (credentialsSecretRef, tlsSecretRef) ou un canal de notification (urlSecretRef, webhookSecretRef) lit aussi un secret de votre tenant, mais aucune App ne le référence : déclarez-le avec materialize: true.

secrets/slack-webhook.yml

apiVersion: ssm.stackngo.io/v1alpha1
kind: SSMSecret
metadata:
  name: slack-webhook
spec:
  length: 0             # la valeur vient de Slack : vous la posez avec sng secret set
  materialize: true     # utilisable par vos sites statiques et canaux de notification

sng apply secrets/slack-webhook.yml
printf '%s' 'https://hooks.slack.com/services/T000/B000/XXXX' > /tmp/slack-url
sng secret set slack-webhook --from-file /tmp/slack-url
rm /tmp/slack-url

Ce que vous obtenez :

• dès que le secret a une valeur, il est utilisable sous son nom (slack-webhook) et avec ses clés (value pour une valeur simple, vos clés pour un secret posé avec --data) par les sites statiques et les canaux de notification du tenant, dans les 10 minutes au plus ;
• chaque nouvelle version, rotation comprise, leur parvient dans les 5 minutes ;
• un secret déjà posé avec sng secret set s'adopte de la même façon : déclarez un SSMSecret du même nom avec length: 0 et materialize: true, la valeur existante est conservée.

Si un autre secret du même nom existe déjà dans votre tenant (celui d'un robot du registre ou d'une application SSO, par exemple), il n'est jamais écrasé : le SSMSecret passe en Error avec le message the value could not be made available to the other resources of the tenant. Choisissez un autre nom.

6. Supprimer

sng kind delete SSMSecret db-password

Le manifeste est retiré de votre tenant et le secret est supprimé avec lui, en moins d'une minute. Le secret n'est plus listé ni lisible.

La suppression ne détruit pas les versions : sng secret restore db-password remet le secret en service avec toutes ses versions, et un sng secret set db-password ultérieur le recrée sous le même nom (voir Versions et restauration).

Ne supprimez pas le secret par en-dessous

sng secret delete db-password sur un secret déclaré par manifeste laisse le manifeste en place, et celui-ci ne redevient pas actif tout seul. Supprimez le manifeste, ou, si vous voulez garder le secret, restaurez-le avec sng secret restore db-password.

Vérification

sng kind get SSMSecret db-password      # le manifeste appliqué, puis son état en commentaires
sng secret describe db-password    # le secret créé : version_id ≥ 1, rotation si rotateDays > 0

sng kind get affiche le manifeste enregistré, suivi de son état (# status: : phase Pending, Active ou Error, et le message). sng secret describe confirme que le secret a une valeur : version_id: "1" (ou plus) et, le cas échéant, rotation_enabled, rotation_days, next_rotation_date. Un secret déclaré vide répond version_id: "0" tant que vous n'avez pas fait set. Si describe répond secret not found plusieurs minutes après l'application, la déclaration a échoué : voir « Si ça ne marche pas » ci-dessous.

Si ça ne marche pas

Ce que vous voyez	Cause	Correction
apply refuse : « rotateDays needs a generated value (length > 0) »	rotateDays sur un secret déclaré vide	Donner une length > 0, ou retirer rotateDays
apply refuse un length, un rotateDays ou une classe	Valeur hors bornes (voir ci-dessous)	Corriger la valeur
sng secret describe répond version_id: "0"	Secret déclaré vide, en attente de sa valeur	sng secret set NAME
secret not found plusieurs minutes après l'application	La déclaration a été refusée, souvent par une policy du tenant (« forbidden by the tenant policies »)	Vérifier sng tenant policy list ; ne pas contredire les policies gérées des secrets
Le secret ne revient pas après sng secret delete	Le secret a été supprimé sans son manifeste	sng secret restore NAME, ou supprimer le manifeste
Error : the value could not be made available to the other resources of the tenant	materialize: true et un autre secret du même nom existe déjà dans le tenant	Renommer le SSMSecret
Site statique ou canal de notification : secret introuvable	Le secret n'est pas déclaré avec materialize: true, ou n'a pas encore de valeur	Déclarer un SSMSecret avec materialize: true, poser la valeur, puis laisser au site ou au canal le temps de la relire (jusqu'à 15 minutes pour un canal)

Pour aller plus loin

• La plateforme ne voit pas vos valeurs : pour un secret déclaré, elle peut seulement faire générer une valeur, jamais en poser une de son choix ni la relire. Laissez en place les policies gérées réservées aux secrets (visibles dans sng tenant policy list) : si une de vos policies les détache ou les contredit, vos SSMSecret passent en Error « forbidden by the tenant policies ».
• Vocabulaire des classes : letters du manifeste devient lower + upper dans la politique de génération, numbers devient number, symbols devient symbol. La valeur contient au moins un caractère de chaque classe retenue.
• Validation : l'API refuse à l'application un rotateDays > 0 avec length: 0 (« rotateDays needs a generated value (length > 0) »), un length hors de 0–4096, un rotateDays hors de 0–3650, une classe inconnue, une description de plus de 1024 caractères.
• Délais : un secret en attente (Pending) est revérifié toutes les 10 minutes, un secret actif (Active) toutes les 6 heures, et une minute après chaque échéance de rotation.
• Un secret référencé par une App avant d'être déclaré est créé en attente automatiquement (sans manifeste). Vous pouvez ensuite le déclarer par SSMSecret : la déclaration adopte le secret existant.

Voir aussi

• Référence des manifestes (page SSMSecret)
• Créer et lire un secret
• Rotation
• Injecter un secret dans une App
• Le cycle validate, plan, apply
• Référence CLI : sng secret create