sng secret

Disponible

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

Le groupe sng secret gère les valeurs secrètes de votre tenant : création, lecture, versions, rotation, suppression. Il agit sur le service de secrets, pas sur vos manifestes — à l'exception de sng secret create, qui produit et applique un manifeste SSMSecret.

Toutes les commandes exigent une session sur le tenant (sng tenant use NAME) ; sinon : tenant session required: run sng tenant use NAME. Les flags globaux (--config, --json, -v, --version) sont décrits dans l'index de la CLI.

Nom d'un secret (argument NAME partout) : minuscules, chiffres, ., _, - ; 128 caractères au plus ; ni / ni ... Sinon : invalid secret name: use lowercase letters, digits, dots, underscores or hyphens.

Actions IAM par commande :

Commande	Action IAM	Route
list	ssm:list	GET /v1/secrets
describe	ssm:describe	GET /v1/secrets/{name}
get	ssm:read	GET /v1/secrets/{name}/value
set	ssm:write	PUT /v1/secrets/{name}
create	deploy:write (apply) ; la plateforme déclare ensuite le secret	POST /v1/apply
versions	ssm:describe	GET /v1/secrets/{name}/versions
rotate	ssm:read puis ssm:write	GET …/value puis PUT /v1/secrets/{name}
restore	ssm:write	POST /v1/secrets/{name}/restore
delete	ssm:delete	DELETE /v1/secrets/{name}

Un refus renvoie 403 forbidden ; une absence de session 403 tenant session required.

sng secret list

sng secret list [--json]

Liste les secrets du tenant, sans valeurs.

Flag	Type	Défaut	Description
(aucun flag propre)

sng secret list

NAME          KEYS  UPDATED
api-key             2026-10-07T09:12:41Z
db-password         2026-10-07T09:10:03Z

Sans secret : no secrets. La colonne KEYS est vide dans cette version (la liste ne charge pas les clés ; utilisez describe).

Sortie --json : {"secrets": [{"name": "…", "updated_at": "…", "version_id": "3", "version_stages": {"current": "3"}}]}.

sng secret describe

sng secret describe NAME

Métadonnées d'un secret, toujours en JSON : clés, version courante, rotation. Jamais la valeur.

Argument	Description
NAME	nom du secret

sng secret describe db-password

{
  "name": "db-password",
  "keys": ["value"],
  "updated_at": "2026-10-07T09:10:03Z",
  "version_id": "3",
  "rotation_enabled": true,
  "rotation_days": 30,
  "next_rotation_date": "2026-11-06T09:10:03Z",
  "version_stages": { "current": "3" },
  "bindings": {
    "env_from_secret": { "name": "runtime-env", "key": "db-password" },
    "external_secret_remote_ref": { "key": "db-password", "property": "value" }
  }
}

rotation_* et next_rotation_date n'apparaissent que si une rotation est armée. version_id: "0" signale un secret déclaré sans valeur. Le bloc bindings est un héritage à ignorer.

Erreurs : secret not found (404) si le secret n'existe pas ou a été supprimé.

sng secret get

sng secret get NAME [--version-id ID] [--key KEY] [--out-file PATH]

Lit la valeur d'un secret. Sans --key, imprime le JSON des clés ; avec --key, imprime la valeur brute de cette clé.

Argument	Description
NAME	nom du secret

Flag	Type	Défaut	Description
--version-id	string	(courante)	numéro de version à lire (1, 2, …)
--key	string		extraire une clé du secret
--out-file	string		écrire dans ce fichier (permissions 0600) au lieu de la sortie standard

sng secret get db-password
sng secret get db-password --key value
sng secret get db-password --version-id 1 --key value --out-file ./old

{
  "value": "S3cr3t"
}
S3cr3t
wrote ./old (mode 0600)

Le message wrote … est émis sur la sortie d'erreur. Un secret sans valeur renvoie null.

Erreurs : key "x" not found in secret ; secret not found (404).

sng secret set

sng secret set NAME [--value V | --from-file PATH | --data K=V ...]
                    [--length N] [--contains CLASSES] [--exclude-chars CHARS]
                    [--no-lowercase] [--no-uppercase] [--no-numbers] [--no-symbols]
                    [--require-each-type[=false]]
                    [--rotation N] [--rotation-key KEY]

Crée ou met à jour un secret (nouvelle version). Sans --value, --from-file ni --data, une valeur aléatoire est générée (16 caractères : lettres, chiffres, ponctuation) et stockée sous la clé value.

Argument	Description
NAME	nom du secret

Flag	Type	Défaut	Description
--value	string		valeur en clair (déconseillé : visible dans l'historique du shell)
--from-file	string		lire la valeur dans un fichier, tel quel (recommandé)
--data	k=v, répétable		paires clé=valeur ; le secret a alors plusieurs clés
--length	int	16	longueur de la valeur générée (1–4096)
--contains	liste	(toutes)	classes à utiliser : letter, number, symbol, lower, upper (alias : letters, alpha, numbers, digit, digits, symbols, punctuation, lowercase, uppercase) ; exclusif avec les --no-*
--exclude-chars	string		caractères jamais utilisés
--no-lowercase	bool	false	pas de minuscules
--no-uppercase	bool	false	pas de majuscules
--no-numbers	bool	false	pas de chiffres
--no-symbols	bool	false	pas de ponctuation
--require-each-type	bool	true	au moins un caractère de chaque classe retenue
--rotation	int	off	le serveur renouvelle la valeur tous les N jours (1–3650) ; 0 désarme ; absent = planification inchangée
--rotation-key	string		clé à renouveler pour un secret multi-clés (défaut : son unique clé) ; exige --rotation

Règles :

• Les flags de génération (--length, --contains, --exclude-chars, --no-*, --require-each-type) ne s'appliquent qu'à une valeur générée. Avec une valeur fournie ils sont refusés : --length only applies to a generated value (without --from-file, --data or --value) — sauf --length, --contains, --exclude-chars, --require-each-type quand --rotation est présent : ils décrivent alors la valeur que le serveur générera à l'échéance.
• --contains et les --no-* sont exclusifs : --contains and the --no-* flags are mutually exclusive.
• --data exige la forme k=v : --data format expected key=value.

sng secret set db-password
sng secret set db-password --from-file ./pw --rotation 30 --length 24
sng secret set shop-api --data DATABASE_URL=postgres://… --data SMTP_PASSWORD=xyz

secret "db-password" saved with a generated 16-character value (sng secret get db-password)
secret "db-password" saved
secret "shop-api" saved

Sortie --json : les métadonnées du secret (même forme que describe, sans bindings).

Erreurs typiques : --length 3 is too short to include each of the 4 character types ; no characters left to generate a value: relax the --no-* or --exclude-chars options ; --rotation-key requires --rotation ; value or data required (400, corps vide côté API) ; forbidden (403).

sng secret create

sng secret create NAME [--length N] [--rotation N] [--contains CLASSES]
                       [--description TEXT] [--dry-run]

Déclare un secret par manifeste : produit un manifeste SSMSecret et l'applique comme sng apply (tenant de la configuration locale requis). La plateforme crée ensuite le secret, génère sa valeur si --length > 0, et le supprimera avec le manifeste. La valeur n'apparaît jamais dans le manifeste. Voir Déclarer un secret dans un manifeste.

Argument	Description
NAME	nom du secret et du manifeste

Flag	Type	Défaut	Description
--length	int	16	longueur de la valeur générée (0–4096) ; 0 = déclaré vide, valeur posée ensuite avec set
--rotation	int	0	renouvellement tous les N jours (0–3650) ; exige --length > 0
--contains	liste	(toutes)	classes : letters, numbers, symbols (alias letter, alpha, number, digit, digits, numbers, symbol, punctuation) ; exige --length > 0
--description	string		description visible dans describe
--dry-run	bool	false	imprime le manifeste sans l'appliquer

sng secret create db-password --length 20 --rotation 30
sng secret create smtp-password --length 0
sng secret create api-key --contains letters,numbers --dry-run

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

Sortie de --dry-run :

apiVersion: ssm.stackngo.io/v1alpha1
kind: SSMSecret
metadata:
  name: api-key
spec:
  length: 16
  contains:
    - letters
    - numbers

Sortie --json : {"uploads": [...]}.

Erreurs typiques : --rotation needs a generated value: --length must be > 0 ; --contains needs a generated value: --length must be > 0 ; --contains "x" unknown: expected letters, numbers or symbols ; --length must be between 0 and 4096 ; --rotation must be between 0 and 3650 days ; tenant session required: run sng tenant use NAME.

sng secret versions

sng secret versions NAME [--json]

Liste les versions d'un secret (numéro, date). Pas de valeur.

Argument	Description
NAME	nom du secret

sng secret versions db-password

VERSION  STAGES  CREATED
1                2026-10-07T09:10:03Z
2                2026-10-07T09:31:48Z

STAGES est toujours vide dans cette version. Secret sans valeur : no versions.

Sortie --json : {"versions": [{"version_id": "1", "stages": [], "created_at": "…"}]}.

sng secret rotate

sng secret rotate NAME [--key KEY]
                       [--length N] [--contains CLASSES] [--exclude-chars CHARS]
                       [--no-lowercase] [--no-uppercase] [--no-numbers] [--no-symbols]
                       [--require-each-type[=false]]
                       [--rotation N] [--rotation-key KEY]

Remplace la valeur par une nouvelle valeur aléatoire, stockée comme nouvelle version. La génération se fait dans la CLI, avec les mêmes flags que set. Pour un secret multi-clés, --key désigne la clé renouvelée ; les autres sont conservées.

Argument	Description
NAME	nom du secret

Flag	Type	Défaut	Description
--key	string	(unique clé)	clé à renouveler dans un secret multi-clés
flags de génération			identiques à set : --length, --contains, --exclude-chars, --no-*, --require-each-type
--rotation, --rotation-key			identiques à set : armer ou modifier la rotation planifiée en même temps

sng secret rotate db-password
sng secret rotate shop-api --key SMTP_PASSWORD --length 32
sng secret rotate db-password --rotation 30

secret "db-password" rotated: new 16-character value (sng secret get db-password)
secret "shop-api" rotated: new 32-character value for key "SMTP_PASSWORD"

Erreurs typiques : the secret holds several keys (DATABASE_URL, SMTP_PASSWORD): choose one with --key ; key "x" not found in the secret ; secret not found (404) ; forbidden (403, il faut ssm:read et ssm:write).

sng secret restore

sng secret restore NAME

Annule la suppression d'un secret : il revient avec sa valeur, toutes ses versions et sa planification de rotation. Action ssm:write.

Argument	Description
NAME	nom du secret

sng secret restore db-password

secret "db-password" restored

Restaurer un secret qui n'est pas supprimé réussit sans rien changer. Dans cette version, aucun délai de récupération n'est appliqué : un secret supprimé reste restaurable. Voir Versions et restauration.

Erreurs typiques : secret not found (404, aucun secret de ce nom dans le tenant) ; forbidden (403, il faut ssm:write).

sng secret delete

sng secret delete NAME [--yes] [--force] [--recovery-days N]

Supprime un secret. Demande confirmation (tapez oui) sauf avec --yes.

Argument	Description
NAME	nom du secret

Flag	Type	Défaut	Description
--yes, -y	bool	false	confirmer sans invite interactive
--force	bool	false	suppression immédiate sans récupération (ignoré par le serveur dans cette version)
--recovery-days	int	0	fenêtre de récupération en jours (7–30 ; ignoré par le serveur dans cette version)

sng secret delete db-password
sng secret delete db-password --yes

⚠ Suppression définitive du secret "db-password".
Tapez « oui » pour confirmer : oui
secret "db-password" scheduled for deletion (recovery 30 d)

Avec --force : secret "db-password" permanently deleted.

Quel que soit le flag, la suppression est logique côté serveur : le secret disparaît de list, describe et get, ses versions chiffrées ne sont pas purgées. sng secret restore NAME le remet en service avec toutes ses versions ; un sng secret set NAME le recrée sous le même nom en poursuivant les versions.

Erreurs typiques : confirmation requise : relancez avec --yes ou depuis un terminal interactif (entrée non interactive sans --yes) ; secret not found (404) ; forbidden (403).

Voir aussi

• Guides : Créer et lire, Versions et restauration, Rotation, Déclarer dans un manifeste, Injecter dans une App
• Manifeste : SSMSecret
• Commandes voisines : sng apply, sng kind delete SSMSecret NAME, sng template gen SSMSecret NAME