Skip to main content

Versions and restore

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

Each write of a secret creates a new numbered version; the previous ones remain stored and readable. This guide shows how to browse this history, go back to an old value, delete a secret and restore it.

Prerequisites​

  • An existing secret: see Create and read a secret.
  • The rights ssm:describe to list versions, ssm:read to read a value, ssm:write to rewrite or restore, ssm:delete to delete (managed policies readwrite or admin).

1. List versions​

sng secret set db-password --from-file ./v1.txt
sng secret set db-password --from-file ./v2.txt
sng secret versions db-password
VERSION  STAGES  CREATED
1                2026-10-07T09:10:03Z
2                2026-10-07T09:31:48Z

Versions are increasing integers starting from 1. The STAGES column is always empty in this version: there is no "current / previous" label, the highest version is the current one.

2. Read an old version back​

sng secret get db-password --version-id 1
{
  "value": "contenu-de-v1"
}

Without --version-id, get returns the most recent version.

3. Go back to an old value​

There is no rollback command: the history is append-only. To go back to version 1, read it back and rewrite it; it becomes version 3.

sng secret get db-password --version-id 1 --key value --out-file ./old
sng secret set db-password --from-file ./old
rm ./old
sng secret versions db-password
VERSION  STAGES  CREATED
1                2026-10-07T09:10:03Z
2                2026-10-07T09:31:48Z
3                2026-10-07T09:40:12Z

The Apps that consume this secret receive the new version as for any write: see Rotation — how an App sees the new value.

4. Delete a secret​

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

In a script, pass --yes (-y) to skip the confirmation.

After deletion:

  • the secret disappears from sng secret list, describe and get respond 404;
  • if an App references it, already started containers keep the value in memory; those that restart afterwards (a few minutes later at most) stay blocked as long as the secret is not recreated;
  • a later sng secret set db-password recreates the secret under the same name and continues the version numbering (version 4 follows 3); the history is not lost.

Deletion destroys no version: the secret can be restored (next step).

Deletion options

--force and --recovery-days are accepted by the CLI and the API, but have no effect in this version: deletion is the same with or without them, and the message "recovery 30 d" does not announce an actual delay. No delay applies: a deleted secret remains restorable.

5. Restore a deleted secret​

sng secret restore db-password
secret "db-password" restored

The secret comes back as it was when it was deleted: same value, all its versions, same rotation schedule. It shows up again in sng secret list, and describe and get respond again. An App that references it gets it back at its next start.

  • You need the ssm:write action on this secret (managed policies readwrite or admin).
  • Restoring a secret that is not deleted changes nothing and also succeeds: you can rerun the command safely.
  • A name that never existed in your tenant responds secret not found.

Verification​

sng secret describe db-password
sng secret versions db-password

After a deletion, describe fails with secret not found. After sng secret restore, it responds again and versions lists every version from before the deletion. After a new set, version_id resumes at the next value.

If it doesn't work​

What you seeCauseFix
secret not foundThe secret was deleted, or the name is misspelledsng secret list; to put it back into service with its versions, sng secret restore NAME
no versionsSecret declared without a value (version 0)sng secret set NAME
secret not found on sng secret restoreNo secret of that name ever existed in the tenantCheck the name, and the current tenant (sng tenant list)
forbidden (…)ssm:describe, ssm:read, ssm:write or ssm:delete is missingAsk an administrator for the policy

Going further​

  • Why the history is append-only: a stored version is never modified. Rewriting an old value under a new number guarantees that the history stays faithful.
  • A secret declared without a value (sng secret create NAME --length 0, or referenced by an App before it exists) is at version 0: versions returns no versions and get returns no data until you run set.
  • Secret declared by manifest: if the secret is carried by an SSMSecret manifest, delete the manifest (sng kind delete SSMSecret NAME) rather than the secret, otherwise the manifest stays pending. See Declare a secret by manifest.
  • API: GET /v1/secrets/{name}/versions (ssm:describe), GET /v1/secrets/{name}/value?version_id=N (ssm:read), DELETE /v1/secrets/{name} (ssm:delete, response 204), POST /v1/secrets/{name}/restore (ssm:write, response 204, 404 if the secret is unknown).

See also​