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:
| Step | What happens |
|---|---|
| 1 | create NAME_rotating with the new content — NAME's labels plus the marker label swarmexec.rotating-for=NAME |
| 2 | switch every service that uses NAME to NAME_rotating — one ServiceUpdate per service, then wait for its rolling update to converge |
| 3 | remove the old NAME, which nothing references any more |
| 4 | create NAME again: the new content, the original labels (com.docker.stack.namespace included, so docker stack rm still removes it) |
| 5 | switch every service back to the new NAME, and wait for convergence again |
| 6 | remove NAME_rotating |
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.
| Flag | Default | Description |
|---|---|---|
--from-file | — | read the new value from this file, byte for byte (binary is fine here) |
--from-stdin | false | read the new value from stdin, byte for byte — echo adds a newline, printf %s does not |
-y, --yes | false | do 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 |
--timeout | 5m | how 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.
See the recipe: rotate a secret and keep its name.