Docker Swarm Fundamentals, Services, Stacks, Secrets, Overlay Networks, Rolling Updates, and Legacy Estate Support: Concepts, Architecture, and Mental Model

1. Why Swarm operations need a different mental model

A standalone container is primarily a daemon-local object. A Swarm service is a cluster desired-state object. The manager records what should exist, the scheduler creates tasks to satisfy that specification, and worker Engines materialize those tasks as containers. Troubleshooting therefore starts with the service and task graph—not with whichever container happens to be visible on one node.

Current Docker still ships Swarm mode inside Docker Engine. Docker’s own guidance says to use Swarm mode when Swarm is the intended production runtime; otherwise use Compose for non-Swarm deployments. “Legacy estate” in this chapter means an existing Swarm environment that deserves competent support and an explicit platform decision, not an unsupported or removed feature.

2. Mental model: desired state becomes tasks

flowchart TD
  A[Manager Raft state] --> B[Service spec + version]
  B --> C[Scheduler]
  C --> D[Task on node]
  D --> E[Container process]
  F[Overlay network] --> D
  G[Secret / config grants] --> D
  H[Image digest] --> D
  E --> I[Observed task state]
  I --> J[Manager reconciliation]
  J --> C
  B --> K[Rolling update / rollback policy]
  K --> C
            

The manager’s service specification is authoritative desired state. A task is a one-way scheduling unit tied to one service slot; when a task fails or is replaced, the orchestrator creates a new task rather than “repairing” the old task in place. The container is the node-local runtime realization of that task.

3. Evidence domains you must not collapse

4. Managers, workers, and Raft quorum

Managers maintain replicated cluster state through Raft and also expose the Swarm management API. Workers execute tasks but do not participate in Raft. A majority of managers must remain available to change cluster state. With three managers the majority is two; with five it is three. Docker recommends an odd number for fault tolerance and generally a maximum of seven managers.

If quorum is lost, already-running tasks can continue, but the swarm cannot perform management operations or reschedule work. That distinction is operationally critical: “containers still answer” does not mean the control plane is healthy.

5. Services, tasks, and containers

A service is the declarative workload contract: image, command, replicas or global mode, networks, secrets, placement, resources, restart/update policy, and publications. A task is a scheduled attempt to realize one part of that service. Containers are created from tasks on worker Engines. Because failed tasks remain in task history, the task list is often more informative than docker ps.

6. Replicated and global services

7. Overlay networking and ingress

User-defined overlay networks provide service-to-service connectivity across participating Docker daemons. Swarm also creates an ingress overlay used by the routing mesh for published services. Control-plane traffic is encrypted; application data-plane encryption is a separate design choice. A single-node lab can demonstrate object semantics, but it cannot prove cross-host dataplane behavior or availability.

8. Routing mesh versus host-mode publishing

With routing-mesh publication, a published port can be accepted on swarm nodes and routed to an active service task. Host-mode publication bypasses that routing behavior and exposes only where a task is running. Host mode can be useful for deterministic node-local integrations, but it shifts load-balancing and port-collision responsibilities outward.

9. Secrets and configs are Swarm objects

Swarm secrets are stored in the encrypted Raft log and are delivered only to tasks granted access, mounted into an in-memory filesystem by default. Configs are also cluster objects but are not secrets. Both should be versioned as identities in operational evidence; a secret value should never be printed to prove its existence.

10. Rolling update is a controlled desired-state transition

Update parallelism, delay, order, monitor interval, maximum failure ratio, and failure action decide how quickly task generations change and what happens when new tasks fail. Rollback is another desired-state transition. Capture the service spec version and task history before updating so you can prove what changed.

11. Image tags are especially dangerous during distributed updates

A mutable tag can resolve differently across time. For a controlled rollout, record the digest that the service specification uses. docker stack deploy can resolve image references through the registry; after deployment, inspect the service’s ContainerSpec.Image rather than assuming the tag still represents the deployed bytes.

12. Compose and stack are related, not equivalent

docker compose up targets a Compose application on a Docker Engine. docker stack deploy targets Swarm services from a Compose-style file, but Docker documents an important compatibility boundary: stack deploy uses the legacy Compose V3-era model and does not support the entire modern Compose Specification. Validate a stack file as a Swarm deployment artifact rather than assuming every local Compose feature carries over.

13. Read-only first: existing-estate inspection

docker version
docker context show
docker info --format '{{json .Swarm}}'
docker node ls
docker service ls
docker stack ls
docker network ls --filter driver=overlay
docker secret ls
docker config ls

These commands reveal cluster identity and objects without changing membership or desired state. On a worker node, manager-only commands fail; that failure is itself useful evidence about the context you are targeting.

14. Current support boundary

Swarm mode remains a current Docker Engine feature with maintained documentation. Platform selection is nevertheless a separate decision: a team may keep an existing Swarm because its operational requirements fit, or migrate because ecosystem, multi-cluster, policy, autoscaling, or organizational requirements point elsewhere. This course does not rank platforms; it teaches you to bind that decision to requirements and evidence.

Knowledge check

Official references and version notes

• Docker Docs — Swarm mode — current support position and core feature set.
• Docker Docs — How services work — desired state, services, tasks, replicas, constraints, and update behavior.
• Docker Docs — How nodes work — managers, workers, scheduling, and manager-count guidance.
• Docker Docs — Administer and maintain a swarm — quorum, manager distribution, backup, and disaster recovery.
• Docker Docs — Raft consensus — replicated manager state and majority requirements.
• Docker Docs — Manage swarm service networks — overlay, ingress, routing mesh, and control/data-plane traffic.
• Docker Docs — Manage sensitive data with Docker secrets — encrypted Raft storage and in-memory task mounts.
• Docker Docs — Docker configs — immutable configs and service/stack lifecycle.
• Docker Docs — Apply rolling updates to a service — update delay, parallelism, and task replacement.
• Docker Docs — Rolling update tutorial — observing task transitions during updates.
• Docker Docs — Deploy a stack to a swarm — manager-only stack deployment and Compose-file compatibility warning.
• Docker CLI — docker stack deploy — current flags including image digest resolution and registry auth propagation.
• Docker CLI — docker service update — rolling-update, rollback, image, secret, config, and publish controls.
• Docker Engine 29 release notes — current Engine-era compatibility baseline.