Docker Swarm Fundamentals, Services, Stacks, Secrets, Overlay Networks, Rolling Updates, and Legacy Estate Support: Configuration, Design Choices, and Tradeoffs

1. Design starts with the control-plane requirement

Do not choose Swarm because a Compose file already exists, and do not migrate away solely because the estate is old. Ask what the workload requires: one host or many, desired-state rescheduling, rolling updates, secrets/config distribution, placement constraints, service discovery, routing, policy ecosystem, cross-cluster operations, and team skills.

2. Standalone Compose versus Swarm versus Kubernetes boundary

3. Replicated versus global

Replicated mode expresses a target count. Global mode expresses one task on every eligible node. Use replicated mode when capacity is a count you want the scheduler to place; use global mode when node membership itself defines desired instances, such as a host-level agent. Constraints and node availability still determine eligibility.

4. Manager count and quorum design

Place managers across independent failure domains. An odd count helps fault tolerance but cannot protect against correlated infrastructure failure or bad operational actions.

5. Routing mesh versus host-mode publish

6. Update policy is a failure-containment policy

parallelism=1 limits blast radius but lengthens rollout. start-first can reduce interruption but temporarily increases resource and port pressure. stop-first minimizes overlap but may reduce availability. pause preserves the failed rollout state for diagnosis; automatic rollback can reduce exposure but may erase the moment when humans should capture first-failure evidence. Choose deliberately.

7. Mutable tags versus digest-bound service specs

Human release tags can remain part of the workflow, but the service should be traceable to the exact digest selected during deployment. During incident review, record both the release alias and the stored service image reference. Rebuilding a tag and calling it “the same release” breaks evidence continuity.

8. Secret lifecycle and rotation

Secrets are immutable objects. Rotation is typically “create new secret → update service grant → verify new tasks → remove old secret after no service references it.” This is different from editing a file in place. The secret value is not evidence; object ID/name, grant, task generation, and application success are.

9. Stack compatibility is a deployment contract

Current Docker documentation still warns that docker stack deploy uses the legacy Compose V3-era format and is not compatible with the entire latest Compose Specification. Treat the stack file as its own validated artifact. Provider-specific Compose extensions, local bind assumptions, profiles, and development/watch features require explicit review.

10. Platform support versus platform fit

Swarm mode is currently supported in Docker Engine and has maintained documentation. That factual status does not decide whether a new system should use it. A decision record should list application requirements, operational capabilities, ecosystem dependencies, migration cost, skill availability, failure modes, and support obligations—then document the chosen platform without rewriting history.

11. Worked scenario: existing three-manager estate

Suppose an estate has three managers across three zones, eight workers, ten services, and a stable operational team. A proposed migration promises a richer policy ecosystem but introduces a new control plane, observability stack, deployment API, and training burden. The correct engineering move is not “Swarm is old, migrate” or “it works, never change.” First capture current service SLOs, manager/quorum health, release/rollback performance, security gaps, missing platform capabilities, and migration test evidence.

12. Decision matrix

13. Evidence-first design record template

Decision: keep / migrate / reduce scope
Current swarm: <ID>, managers=<N>, workers=<N>
Requirements: <availability, policy, scale, compliance, ecosystem>
Image policy: digest-bound? <yes/no>
Quorum design: <manager count + failure domains>
Network publication: <ingress/host/external LB>
Secret/config lifecycle: <rotation procedure>
Update policy: <parallelism/order/failure action>
Known gaps: <measured>
Target prerequisites: <versions, skills, integrations>
Validation evidence: <tests/incident drills>
Rollback or coexistence path: <documented>

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.