Tune Docker Swarm Safely with docker swarm update

docker swarm update changes cluster-wide Swarm settings in one short command. Picking safe values and watching the cluster afterwards is the real work, so allow about ten minutes for a planned change plus verification.

Before you start

Use a manager node. This is a cluster-management command, not something a worker can run. You also need access to the Docker daemon, normally through the current user's Docker socket permissions. Use sudo only if that is how this host is administered.
Record the current state. Run these read-only checks before changing anything:

docker version
docker info --format 'Swarm={{.Swarm.LocalNodeState}} Control={{.Swarm.ControlAvailable}}'

On a usable manager, the second command should report Swarm=active and Control=true. The local CLI used for this guide is Docker 29.8.1 from the docker-ce-cli package version 5:29.8.1-1~ubuntu.24.04~noble. The command has seven options in total: autolocking, certificate expiry, dispatcher heartbeat, external CA, Raft snapshots, snapshot interval and task history.

Checkpoint: do not continue if the node is not an active manager. Move to one and repeat the checks; a worker cannot safely apply this update.

1. Choose one setting and write down its rollback value

Do not combine unrelated changes in one maintenance window. The command reports what it applied, not a general before-and-after diff, so keep a small change record yourself: old value, new value, reason, operator. Restoring later just means running the same command with the previous value.

The local defaults are:

Option	Default	What it controls
`--cert-expiry`	`2160h0m0s`	Validity period for node certificates
`--dispatcher-heartbeat`	`5s`	Dispatcher heartbeat period
`--snapshot-interval`	`10000`	Log entries between Raft snapshots
`--max-snapshots`	`0`	Additional Raft snapshots retained
`--task-history-limit`	`5`	Task history retention limit

Durations use a unit such as h, m or s. Counts are unsigned for the snapshot options, while the task history limit is a plain integer. Keep the unit explicit: 720h is clear, a bare number is not a valid duration.

2. Change a certificate validity period

Set the complete value rather than leaning on a default. This example changes certificate validity to 720 hours:

docker swarm update --cert-expiry 720h

The official example uses this same option and form. It is still a cluster setting, so treat one command as a genuine operational change. Do not shorten certificate validity during an incident unless you understand the effect on node certificates and have a recovery window ready.

To undo the example, restore the value you recorded. If that recorded value was the local default:

docker swarm update --cert-expiry 2160h0m0s

3. Change Raft snapshot and task history settings

Snapshot settings affect the swarm's Raft state rather than any single service. This example keeps two additional snapshots and creates one after every 5,000 log entries:

docker swarm update \
  --max-snapshots 2 \
  --snapshot-interval 5000

Task history is a separate retention limit. This keeps ten task records:

docker swarm update --task-history-limit 10

These changes can alter disk use and how much history you have to diagnose a service later. Pick values from observed workload and storage capacity, not from a copied command. If monitoring shows an unwanted effect, restore the earlier values:

docker swarm update \
  --max-snapshots <previous-max-snapshots> \
  --snapshot-interval <previous-snapshot-interval> \
  --task-history-limit <previous-task-history-limit>

Replace every angle-bracket placeholder before running the command. The local manpage lists 0 as the default for additional snapshots, 10000 for the interval and 5 for task history.

4. Handle autolocking, heartbeat and external CA carefully

Warning: --autolock is security-sensitive. Turning it on changes how a restarted manager gets back into service, and losing the required unlocking material can turn a short restart into a long outage. Make sure the operator who owns the swarm's recovery process is in the room before you flip this. The option is boolean:

docker swarm update --autolock=true

Heartbeat and external certificate authorities also affect cluster operation. The CLI accepts --dispatcher-heartbeat <duration> and --external-ca <specification>, but the local manpage does not define a safe external-CA specification or a site-specific heartbeat value: do not invent either. Check the Docker release documentation and your existing swarm configuration first, and test the change on a disposable swarm before touching production.

5. Verify the change and watch for failure

A successful command is not proof every manager and worker is healthy. Immediately repeat the manager check and inspect node and service state:

docker info --format 'Swarm={{.Swarm.LocalNodeState}} Control={{.Swarm.ControlAvailable}}'
docker node ls
docker service ls

Expect the local node to stay an active manager, and chase up any manager that is unavailable or any service with an unexpected replica count. If the update fails, keep the error text and do not keep retrying with guessed values. Check the option syntax with:

docker swarm update --help

Some updates deserve a maintenance decision precisely because managers coordinate cluster state. Announce the change if your operating procedure requires it, and keep the rollback command ready in the same terminal session.

Done means

Right node. The command ran on an active manager with Docker daemon access.
One change at a time. Only the intended option or options changed, with old values recorded.
Durations correct. Durations include explicit units and every placeholder was replaced.
State verified. docker info, docker node ls and docker service ls show the expected swarm state.
Rollback ready. A tested rollback command is on hand, especially for autolocking or other security-sensitive changes.