SSMSecret

Disponible

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

apiVersion	ssm.stackngo.io/v1alpha1
kind	SSMSecret
Appliqué par	sng apply
Commande sng liée	sng secret create NAME génère et applique ce manifeste ; sng secret set, get, describe agissent sur la valeur

À quoi ça sert

Un SSMSecret déclare qu'un secret existe dans votre tenant et comment sa valeur est produite : longueur, classes de caractères, rotation. La valeur elle-même n'apparaît jamais dans le manifeste : soit le serveur de secrets la génère à la création, soit vous la posez ensuite avec sng secret set.

C'est la façon déclarative de gérer vos secrets : le manifeste est versionné avec le reste de votre tenant, la suppression du manifeste supprime le secret, et une valeur déjà présente n'est jamais écrasée par une nouvelle application du manifeste.

Exemple minimal

db-password.yml

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

Équivalent en une commande : sng secret create db-password.

À l'application, le serveur génère une valeur de 16 caractères (lettres, chiffres, symboles). Lisez-la avec sng secret get db-password.

Exemple complet commenté

db-password.yml

apiVersion: ssm.stackngo.io/v1alpha1
kind: SSMSecret
metadata:
  name: db-password            # nom du secret : minuscules, chiffres, . _ - (max 128)
spec:
  length: 24                   # longueur de la valeur générée ; 0 = déclaré vide,
                               # vous posez la valeur avec sng secret set (défaut 16)
  rotateDays: 30               # nouvelle valeur générée tous les 30 jours ; 0 = jamais.
                               # Exige length > 0. La rotation remplace la valeur
                               # même si vous l'aviez posée à la main.
  contains: [letters, numbers] # classes de caractères : letters, numbers, symbols ;
                               # vide = toutes. Au moins un caractère de chaque classe.
  description: "Mot de passe Postgres de l'app shop"   # visible dans sng secret describe
  materialize: false           # true : utilisable aussi par vos sites statiques (CDNSite)
                               # et canaux de notification, même si aucune App ne le lit

Équivalent : sng secret create db-password --length 24 --rotation 30 --contains letters,numbers --description "Mot de passe Postgres de l'app shop". materialize n'a pas de flag : ajoutez-le au manifeste (sng secret create … --dry-run).

Champs

Règles de validation croisées (appliquées au moment du sng apply) :

• rotateDays ne peut être renseigné (différent de 0) que si length est strictement positif : « rotateDays needs a generated value (length > 0) ». Une rotation a besoin d'une forme de valeur à générer.
• contains ne peut contenir que letters, numbers, symbols, chacun au plus une fois (3 éléments maximum).
• La CLI ajoute une règle de confort : sng secret create --contains … --length 0 est refusé, car les classes ne servent qu'à une valeur générée.

SSMSecret

SSMSecret déclare un secret du service de secrets : son existence et la façon dont sa valeur est produite, jamais la valeur elle-même.

Champ	Description	Défaut	Validation
apiVersion string	ssm.stackngo.io/v1alpha1
kind string	SSMSecret
metadata ObjectMeta	Seul metadata.name est à renseigner (nom de la ressource dans votre tenant).
spec SSMSecretSpec
status SSMSecretStatus

SSMSecretSpec

SSMSecretSpec déclare un secret de votre tenant.

Le manifeste dit que le secret existe et comment sa valeur est produite ; la valeur elle-même n'apparaît jamais dans le manifeste : elle reste chiffrée dans le service de secrets.

Champ	Description	Défaut	Validation
length integer	Length de la valeur générée. 0 = secret déclaré vide : l'utilisateur pose la valeur (sng secret set). Une valeur existante n'est jamais écrasée à la création.	16	Maximum: 4096 Minimum: 0
rotateDays integer	RotateDays renouvelle la valeur tous les N jours (0 = pas de rotation). La rotation remplace la valeur quelle que soit son origine.		Maximum: 3650 Minimum: 0 Optional: {}
contains string array	Contains liste les classes de caractères de la valeur générée ; vide = toutes. Au moins un caractère de chaque classe retenue.		MaxItems: 3 items:Enum: [letters numbers symbols] Optional: {}
description string	Description du secret, visible dans sng secret describe.		MaxLength: 1024 Optional: {}
materialize boolean	Materialize rend le secret utilisable par les autres ressources du tenant (site statique, canal de notification), même si aucune application ne le lit. La valeur suit chaque nouvelle version, rotation comprise. Sans ce champ, le secret n'est mis à disposition que des applications qui le référencent.		Optional: {}

SSMSecretStatus

SSMSecretStatus reflète l'état du secret dans le service de secrets.

Champ	Description	Défaut	Validation
phase string	Phase : Pending (déclaré sans valeur, à poser avec sng secret set), Active ou Error.		Optional: {}
version integer	Version courante de la valeur du secret (0 = pas encore de valeur).		Optional: {}
nextRotationAt Time	NextRotationAt est la prochaine échéance de rotation.		Optional: {}
observedGeneration integer	Dernière version du manifeste prise en compte par la plateforme.		Optional: {}
message string	Message : explication de la phase (action attendue en Pending, cause en Error).		Optional: {}
conditions Condition array	Conditions du secret (Ready…), avec leur reason et un message lisible.		Optional: {}

Statut et conditions

Condition	True	False
Ready	Le secret est Active dans le service de secrets : il a une valeur, les Apps peuvent le consommer	Le secret est déclaré sans valeur (Pending) ou la déclaration a échoué (Error)

Le reason de la condition reprend la phase (status.phase).

reason / phase	Signification	Action
Pending	Déclaré avec length: 0, aucune valeur encore ; ou le tenant vient d'être créé et sa session n'est pas encore accordée (message: waiting for the tenant session)	Posez la valeur : sng secret set NAME. Le statut repasse à Active dans les 10 minutes. Pour un tenant neuf, attendez simplement
Active	Le secret a une valeur (status.version ≥ 1). status.nextRotationAt indique la prochaine rotation si rotateDays > 0	Rien
Error	message: forbidden by the tenant policies (…) : une policy Deny de votre tenant bloque la gestion du secret par la plateforme	Ne détachez pas la policy gérée par la plateforme pour les secrets ; vérifiez vos policies Deny sur secret/*
Error	message décrivant un paramètre invalide (longueur, classes)	Corrigez la spec et réappliquez
Error	message: … is not enrolled	Incident côté plateforme : contactez le support
Error	message: 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 votre tenant (il n'est jamais écrasé) ; ou échec passager, réessayé toutes les 30 secondes	Si le message persiste, renommez le SSMSecret

Autres champs du statut : version (version courante, 0 = pas encore de valeur), nextRotationAt (prochaine rotation), observedGeneration, message. sng kind get SSMSecret NAME les affiche en commentaires sous le manifeste.

Ce qui se passe à l'application

Création. Si le secret n'existe pas, il est créé ; si length > 0 et qu'il n'a aucune valeur, une valeur est générée et enregistrée en version 1. Si une valeur existe déjà (posée avec sng secret set avant ou après la déclaration), elle est conservée telle quelle. La politique de rotation est celle du manifeste.

Mise à jour. Changer length ou contains sur un secret qui a déjà une valeur ne modifie pas cette valeur : ces champs ne décrivent que la première génération et les rotations à venir. Changer rotateDays met à jour la politique de rotation (0 la désarme). Passer length à 0 désarme une rotation précédemment posée par le manifeste.

Délais. Un secret Pending qui reçoit sa valeur repasse Active dans les 10 minutes. Après une rotation, la nouvelle version apparaît dans le statut environ une minute après l'échéance.

materialize: true. Dès que le secret a une valeur, il devient utilisable, sous le même nom et avec les mêmes clés, par les ressources du tenant qui lisent un secret sans être une App : credentialsSecretRef et tlsSecretRef d'un CDNSite, urlSecretRef et webhookSecretRef d'un NotificationChannel. Chaque nouvelle version, rotation comprise, leur parvient dans les 5 minutes. Sans ce champ, le secret n'est mis à disposition que des Apps qui le référencent. Voir Déclarer un secret par manifeste.

Ce qui se passe quand vous supprimez

sng kind delete SSMSecret NAME supprime le secret : il n'est plus listé ni lisible, et les Apps qui l'utilisent ne peuvent plus le lire. Ses versions ne sont pas effacées : sng secret restore NAME le remet en service avec toutes ses versions, et un sng secret set NAME ultérieur le recrée sous le même nom en poursuivant la numérotation des versions (voir Versions et restauration).

Erreurs fréquentes

Symptôme	Cause	Correction
sng apply refuse le manifeste : « rotateDays needs a generated value (length > 0) »	rotateDays > 0 avec length: 0	Donnez une longueur, ou retirez rotateDays
Le statut reste Pending avec « declared without value: set it with sng secret set NAME »	length: 0 : le secret attend sa valeur	sng secret set NAME --from-file …
Vous changez length: 16 en length: 32, la valeur ne change pas	Une valeur existante n'est jamais écrasée	Forcez une nouvelle valeur : sng secret rotate NAME --length 32, ou attendez la rotation planifiée
Vous aviez posé une valeur à la main, elle a été remplacée	rotateDays > 0 : la rotation remplace la valeur quelle que soit son origine	Mettez rotateDays: 0 si la valeur doit rester fixe
Error « forbidden by the tenant policies »	Une policy Deny du tenant refuse ssm:declare ou ssm:rotate	Retirez ce refus, ou rétablissez la policy gérée par la plateforme pour les secrets
Le manifeste réappliqué après un sng secret delete NAME ne redevient jamais Active et le statut ne bouge pas	Le secret a été supprimé sans son manifeste	Restaurez-le avec sng secret restore NAME (ou recréez une valeur avec sng secret set NAME), puis réappliquez
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à	Renommez le SSMSecret
sng kind delete SSMSecret NAME ne finit pas	La suppression du secret est refusée par une policy Deny sur ssm:delete	Retirez ce refus, ou rétablissez la policy gérée par la plateforme pour les secrets

Voir aussi

• Guides : Déclarer un secret dans un manifeste, Créer et lire un secret, Rotation, Injecter un secret dans une App
• CLI : sng secret
• Autres kinds : App (champs env et envFrom)