swarmexec

swarmexec › Docs › Stack export, diff & wait

Stack export, diff & wait_

What is deployed, as a file — and when a deploy is really done.

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.

swarmexec stack ls swarmexec stack export postgres -o postgres.yml swarmexec stack diff postgres.yml postgres

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.

CommandDescription
stack lsthe 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:

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.

swarmexec stack diff shop.yml --ignore 'services.*.deploy.replicas' swarmexec stack diff shop.yml --json | jq .differs

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.

swarmexec stack rm shop swarmexec stack rm shop --yes

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.

swarmexec stack deploy shop.yml --yes && swarmexec wait --stack shop --timeout 3m swarmexec wait api worker --healthy

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.

FlagDefaultDescription
--stack—wait for every service of this stack (in addition to any named)
--timeout5mgive up after this long (exit 1)
--healthyfalsealso require healthy containers (asks the agents)