Docker Swarm Services

A swarm does not run containers directly. You describe a service, and the swarm creates and maintains the containers that fulfil it. A service states the image, the number of copies, the ports, and the update rules. Swarm compares reality with that description every few seconds and corrects any difference.

Creating a Service

docker service create \
  --name web \
  --replicas 3 \
  --publish 80:80 \
  nginx:alpine

The swarm starts three nginx tasks across the available nodes and opens port 80 on every node.

Service "web" (3 replicas)

node1: web.1       node2: web.2       node3: web.3

Listing and Inspecting

docker service ls
docker service ps web
docker service inspect --pretty web
docker service logs web

The ps command shows each task and the node that runs it. This view answers the question of where each copy lives.

Scaling Up and Down

docker service scale web=6
docker service scale web=2

Swarm adds or removes tasks until the count matches. Scaling takes seconds because the image already sits on the nodes or downloads quickly.

Self-Healing in Action

Stop a container on purpose and watch the result.

Desired: 3 replicas
Actual : web.1 web.2 web.3     OK

node2 loses power
Actual : web.1 web.3           only 2 running
Swarm   : starts web.2 on node3
Actual : web.1 web.2 web.3     OK again

Nobody typed a command. The swarm noticed the gap and filled it.

The Routing Mesh

Swarm publishes service ports on every node. A request sent to any node reaches a healthy task, even when that node runs no copy of the service.

Client --> node1:80 (no web task here)
              |
              +--> routing mesh --> web.2 on node2

This design lets a load balancer point at any node, and it spreads traffic evenly across the copies.

Rolling Updates

Update a service to a new image without downtime.

docker service update \
  --image nginx:1.27-alpine \
  --update-parallelism 1 \
  --update-delay 15s \
  web

Time ->  v1 v1 v1
         v2 v1 v1     replace one copy, wait 15 seconds
         v2 v2 v1     replace the next copy
         v2 v2 v2     finished

Users keep receiving responses during the whole process because at least two copies always run.

Rolling Back

docker service rollback web

The command returns the service to its previous definition.

Placement Rules

Constraints decide which nodes may run a service.

docker service create --name db \
  --constraint "node.labels.disk==ssd" \
  postgres:16

Global Services

A global service runs exactly one task on every node. Monitoring agents and log collectors use this mode.

docker service create --name agent --mode global my-monitoring-agent

Deploying Stacks

A stack groups several services in a Compose-style file.

version: "3.9"
services:
  web:
    image: my-web:2.0
    ports:
      - "80:80"
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
  db:
    image: postgres:16
    deploy:
      placement:
        constraints: ["node.role == manager"]

docker stack deploy -c stack.yml shop
docker stack services shop
docker stack rm shop

Common Mistakes

• Using the build option in a stack file. Swarm needs images from a registry.
• Running a database with several replicas and a shared local volume.
• Updating all copies at once, which removes the safety of rolling updates.

Real-World Scenario

An online course platform releases a new version every Thursday evening. Before Swarm, the team put up a maintenance page for ten minutes while they swapped containers. With a rolling update, the platform keeps serving students during the whole release. One Thursday, the new version crashes at startup. Swarm detects the failure on the first replaced copy, pauses the update, and leaves the other copies on the old version. The team runs a rollback command and investigates the problem on Friday morning without any student noticing.

Update Failure Settings

docker service update   --update-failure-action rollback   --update-monitor 30s   web

This setting asks Swarm to watch each new copy for thirty seconds and roll back automatically when a copy fails. The service protects itself from bad releases without human help.

Replicated or Global

Mode         Behavior                         Use for
-----------  -------------------------------  ---------------------
replicated   a fixed number of copies         web servers, APIs
global       one copy on every node           monitoring, log agents

Replicated mode is the default. Choose global mode only when each machine needs its own local helper.

Service Health and Restart Rules

Swarm restarts failed tasks according to a restart policy. The default condition restarts a task whenever it stops. The on-failure condition restarts only after an error exit. Add a maximum attempt count so a broken service does not restart forever and hide the underlying problem.

docker service create --name worker \
  --restart-condition on-failure \
  --restart-max-attempts 5 \
  my-worker

Combine restart rules with health checks. Swarm replaces any task that reports unhealthy, so a frozen process gets fixed even when it never exits by itself. Use docker service ps --no-trunc web to read the full error message behind each failed task.