swarmexec › Docs › Stack export, diff & wait
Stack export, diff & wait_
What is deployed, as a file — and when a deploy is really done.
On this page
Need the exact spec a service is actually running, not a file someone deployed
once? stack export reads it back from the manager — that is what
this page is for. The line between swarmexec and the Docker CLI is on
Next to docker.
stack export / stack diff — a deployed stack as a file
stack export reads a deployed stack back out of the cluster and
writes it as compose-shaped YAML. stack diff compares a stack file
against what is actually deployed and prints a unified diff: a
+ line is something deploying the file would add, a
- is something it would remove. Like
git diff --exit-code it exits 1 when anything
differs, so it works in CI.
In the TUI, E on the Stacks/Services tab offers both for the stack under the cursor — the stack row, a service in it, or a container of one.
Why it does not diff text. A deployed stack carries things the
file never had: the image digest the daemon resolved at deploy time, its own
defaults for restart and update policy, and the stack namespace prefixed onto
every network, secret and volume. Comparing the two as text reports dozens of
differences for a stack that is exactly in sync — which is worse than no tool at
all, because it teaches you to ignore the output. Instead the file is run through
docker's own compose loader and converter, the same code
docker stack deploy uses, and both sides are then reduced by the
same function. The question answered is “would deploying
this file change anything?”, not “are these two files spelled the
same?”. Daemon defaults are dropped from both sides; a value that is
not the default still shows, so nothing real is hidden.
An export is a description, not a backup. A secret's value is
write-only in the engine API — it can never be read back — and a
volume's contents live on the nodes. Both are therefore declared
external, and the exported file says so in its own header:
recreating the stack elsewhere means creating the secrets first. Spec fields the
rendering does not carry (tty, ulimits, seccomp and
AppArmor settings and a few others) are named in the same place, because the
dangerous failure of a comparison tool is not a wrong answer but a confident
silence — so “no differences” always arrives with its caveats attached.
Variables are interpolated from your environment, exactly as
docker stack deploy does. A file containing ${TAG}
therefore describes a different stack for a different TAG, and the
diff depends on the environment it runs in — which is correct: pretending
otherwise would report no change for a deploy that would change the image.
| Command | Description |
|---|---|
stack ls | the stacks deployed on the cluster |
stack export <stack> | write the stack as compose YAML; -o to a file, otherwise stdout |
stack diff <file> [stack] | compare a file against the deployed stack. The stack name defaults to the file's base name; --stack or a second argument overrides it. Exits 1 on any difference |
stack check <file> [stack] | run the security checks of stack deploy without deploying; exits 1 on a finding above informational. Also security check |
stack rm <stack> | remove the stack's services, secrets, configs and networks, after a confirm — see below |
stack deploy next to docker stack deploy
The conversion is docker's own, so the services submitted are the ones
docker stack deploy would submit. Around it, four things are
deliberate:
- The
defaultnetwork is per service. Every service that names no network lands on<stack>_default, and that network is created whenever any service needs it, also when another service names its own networks. (Earlier it was created only if no service named one, and such a file stopped half-applied.) - An existing secret or config is left unchanged, and the deploy says
so. Swarm cannot change the content of either, so a changed file is not
applied; each one is listed (“secret app_key already exists and was left
unchanged”). To roll out new content, create it under a new name.
dockerinstead attempts an update and fails. - Registry credentials are sent only with
--with-registry-auth, exactly as in docker: the local login for each service's image is passed to the manager so nodes without their own login can pull a private image. - The manager's warnings are printed (to stderr, prefixed with the service) instead of being dropped — for example a placement that no node can satisfy yet.
As a pipeline gate. Run nightly, stack diff answers
“does the cluster still match Git?”: exit 0 means no difference,
1 a difference, 2 a usage error, 125
an unreachable manager. A gate that goes red on every harmless change gets
switched off, so --ignore leaves a field out of both sides —
services.*.deploy.replicas for a count an autoscaler moves, with
* for any service name; repeat it for several paths. Every ignored path
is listed under Not compared, so a green result still says what it did not
look at, and a path that matched nothing on either side is called out, because a
typo in an ignore list otherwise ignores nothing, silently.
--json prints the machine form: differs, the hunks,
ignored and not_compared.
See the recipe: catch drift in CI.
stack rm — remove a stack
Removes what docker stack rm removes: every service, secret, config
and network labelled com.docker.stack.namespace=<stack> — the
same removal the TUI runs on a stack row. It lists each object first
and asks; -y/--yes answers in advance, and without a
terminal and without --yes nothing is removed. Two differences from
docker: a network whose endpoints are still draining gets a few seconds before it
counts as stuck, and when something will not go the rest is removed anyway and the
command names exactly what is left behind (exit 125).
A stack with nothing labelled for it is an error, so a typo does not pass as a
success.
wait — until a deploy has actually converged
stack deploy returns when swarm has accepted the change, not
when it works. wait closes that gap for a pipeline: it blocks until
every named service — or every service of --stack — has converged,
then exits 0; it exits 1 with the reason when one
does not.
Converged means no update in flight and as many running tasks as
desired (for a job: its completions reached), held for two polls a few seconds
apart — so even a stable service takes a few seconds, and the moment right after a
deploy, before the manager has started the update, cannot pass for done. Two states
that look settled are failures: an update that paused
(the service runs a mix of old and new tasks) and a rollback that completed during
the wait (it runs the previous spec — the deploy did not take). On timeout every
service still waited for is listed and counted — including one that converged
but has not held it long enough yet (converged, settling) — with the
reason a task is not running, typically the scheduler's own message.
With --healthy every container that has a healthcheck must also report
healthy; a node whose agent cannot report health counts as not yet, never
as healthy. swarmexec only observes and reports — it never rolls back or retries.
| Flag | Default | Description |
|---|---|---|
--stack | — | wait for every service of this stack (in addition to any named) |
--timeout | 5m | give up after this long (exit 1) |
--healthy | false | also require healthy containers (asks the agents) |
See the recipe: a deploy that is really done.