swarmexec

swarmexec › Docs › Rotate a secret, keep its name

Rotate a secret, keep its name_

New content, same name, resumable.

secret rotate — new content, same name

Gives a secret new content without renaming it, so the stack files and service specs that name it stay as they are. Swarm secrets are immutable, and one a service still references cannot be removed — which is why the usual answer is a new name (db_password_v2) and an edit everywhere it is used. Instead, every service using the secret is parked on a temporary secret while the original is replaced underneath it:

StepWhat happens
1create NAME_rotating with the new content — NAME's labels plus the marker label swarmexec.rotating-for=NAME
2switch every service that uses NAME to NAME_rotating — one ServiceUpdate per service, then wait for its rolling update to converge
3remove the old NAME, which nothing references any more
4create NAME again: the new content, the original labels (com.docker.stack.namespace included, so docker stack rm still removes it)
5switch every service back to the new NAME, and wait for convergence again
6remove NAME_rotating
swarmexec secret rotate <name> (--from-file FILE | --from-stdin) [--yes] [--timeout 5m]
$ swarmexec secret rotate db_password --from-file ./db_password.txt $ printf %s "$NEW_TOKEN" | swarmexec secret rotate api_token --from-stdin --yes

Only the secret behind each mount changes. The target path, uid, gid and mode of every reference stay exactly as they were, and a service's other secrets are not touched — inside the container the same file holds the new bytes. All services using the secret are switched, with no choice: the old object can only go once nothing references it. A service scaled to 0 or a global one with no eligible node still gets its spec updated; it simply has no tasks to wait for. A service update that collides with another change (update out of sequence) is retried on a fresh read.

Each service restarts twice — two rolling updates, following the service's own update_config. One service is switched at a time and must converge (no task still on the old secret, every new one running, swarm not reporting the update as paused or rolled back) before the next starts; --timeout bounds each of these waits. Progress goes to stderr, one line per step and service. The value is never printed.

There is no rollback to the old content: the old secret object is deleted in step 3. After a rotation each service's previous version names NAME_rotating, which step 6 deletes as well, so a rollback would aim at a secret that does not exist. swarmexec refuses it (the TUI's rollback and the underlying call check that every secret and config of the previous version still exists, and say which one is gone, changing nothing); docker service rollback has no such check and would start tasks that can never get their file. Keep the old value yourself if you might need it. Once the service is updated again for any other reason, its previous version is that update's, and a rollback works as usual.

Templated and driver secrets. A secret created with a templating driver (docker secret create --template-driver) keeps it: the stand-in and the new secret carry the same templating. A secret served by an external secret driver has no content in swarm to replace, so a rotation of it is refused before anything is touched.

Secrets from a stack file. If the secret was created by docker stack deploy from a file:, swarmexec cannot see that file: put the new content there too. Otherwise the next deploy fails with only updates to Labels are allowed, because the file's content no longer matches the secret's. A secret the stack declares external: true has no such problem. The confirm shows this as a hint whenever the secret carries a stack label.

Resume. If a run stops half-way — a timeout, a paused update, a lost connection, a killed process — the services are left on NAME_rotating, which already holds the new content: a working state, not a broken one. Run the same command again and it reads where the last run stopped from the cluster itself and continues there: services still on NAME → step 2; NAME gone → step 4; NAME re-created and in use → step 5. Every step re-reads the cluster before it acts, so repeating one is harmless. The new value must be given again (the API cannot read a secret back); once NAME has been re-created and services use it, it keeps the content of the run that created it and the confirm says so. A NAME_rotating without the marker label is someone else's secret: the rotation refuses to start rather than touch it.

A secret no service uses goes through the same steps with nothing to switch — nothing restarts. Removing and re-creating it directly would save two API calls but leave a moment where NAME is gone and its labels exist only in a process that might die; the temporary secret keeps them on the cluster, so that case resumes like any other.

FlagDefaultDescription
--from-file—read the new value from this file, byte for byte (binary is fine here)
--from-stdinfalseread the new value from stdin, byte for byte — echo adds a newline, printf %s does not
-y, --yesfalsedo not ask. Without it the affected services and their target paths are listed and a y/N answer is read from the terminal; with no terminal (or with --from-stdin) the command refuses without --yes
--timeout5mhow long to wait for each service's rolling update to converge

The value must not be empty and is limited to 500 KB, checked before anything is touched. Exit code 0 means rotated; 1 a failure (the message says which step, and how to resume when there is something to resume); 2 a usage error; 125 an unreachable manager. In the TUI, r in a secret's detail view does the same.