Skip to main content

Services and Tasks

Chapter objectives​

  • Understand the service and task concepts
  • Create and manage services
  • Configure deployment modes
  • Monitor the state of services

1 - Fundamental concepts​

Hierarchy of Swarm objects​

┌─────────────────────────────────────────────────────────────┐
│                         Stack                                │
│                    (docker-compose.yml)                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│    ┌───────────┐    ┌───────────┐    ┌───────────┐         │
│    │  Service  │    │  Service  │    │  Service  │         │
│    │   "web"   │    │   "api"   │    │   "db"    │         │
│    └─────┬─────┘    └─────┬─────┘    └─────┬─────┘         │
│          │                │                │                │
│    ┌─────┴─────┐    ┌─────┴─────┐    ┌─────┴─────┐         │
│    │  Tasks    │    │  Tasks    │    │  Task     │         │
│    │ (3 repli) │    │ (2 repli) │    │ (1 repli) │         │
│    └───────────┘    └───────────┘    └───────────┘         │
│                                                             │
│    ┌─────────────────────────────────────────────────┐     │
│    │              Containers                          │     │
│    │  web.1  web.2  web.3  api.1  api.2  db.1        │     │
│    └─────────────────────────────────────────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Definitions​

TermDescription
ServiceDefinition of what must run (image, config, replicas)
TaskUnit of work assigned to a node (1 task = 1 container)
ContainerActual instance running on a node

2 - Create a service​

Basic syntax​

docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]

Examples​

# Service simple
docker service create --name web nginx

# Avec nombre de réplicas
docker service create --name web --replicas 3 nginx

# Avec publication de port
docker service create --name web -p 80:80 nginx

# Avec variables d'environnement
docker service create --name api \
  -e NODE_ENV=production \
  -e DB_HOST=db \
  node:18-alpine

# Avec montage de volume
docker service create --name db \
  --mount type=volume,source=db-data,target=/var/lib/postgresql/data \
  postgres:15

Common options​

OptionDescriptionExample
--nameService name--name web
--replicasNumber of replicas--replicas 3
-p, --publishPort publishing-p 8080:80
-e, --envEnvironment variable-e KEY=value
--mountVolume mount--mount type=volume,...
--networkNetwork to use--network my-overlay
--constraintPlacement constraint--constraint node.role==worker

3 - Deployment modes​

Replicated (default)​

Runs N instances distributed across the available nodes:

# 5 réplicas distribués sur le cluster
docker service create --name web --replicas 5 nginx
┌─────────┐  ┌─────────┐  ┌─────────┐
│ Node 1  │  │ Node 2  │  │ Node 3  │
├─────────┤  ├─────────┤  ├─────────┤
│ web.1   │  │ web.2   │  │ web.3   │
│ web.4   │  │ web.5   │  │         │
└─────────┘  └─────────┘  └─────────┘

Global​

Runs exactly 1 instance per node:

# 1 instance sur chaque nœud
docker service create --name agent --mode global prometheus/node-exporter
┌─────────┐  ┌─────────┐  ┌─────────┐
│ Node 1  │  │ Node 2  │  │ Node 3  │
├─────────┤  ├─────────┤  ├─────────┤
│ agent.1 │  │ agent.2 │  │ agent.3 │
└─────────┘  └─────────┘  └─────────┘

Use cases​

ModeUse case
ReplicatedWeb applications, APIs, workers
GlobalMonitoring agents, log collectors, antivirus

4 - Manage services​

List services​

# Liste simple
docker service ls

# Format personnalisé
docker service ls --format "{{.Name}}: {{.Replicas}}"

Inspect a service​

# Informations complètes
docker service inspect web

# Format JSON pretty
docker service inspect web --pretty

# Extraire une valeur
docker service inspect web --format '{{.Spec.Mode.Replicated.Replicas}}'

View a service's tasks​

# Lister les tâches
docker service ps web

# Avec plus de détails
docker service ps web --no-trunc

# Filtrer par état
docker service ps web --filter "desired-state=running"

View logs​

# Logs de toutes les tâches
docker service logs web

# Suivre en temps réel
docker service logs -f web

# Avec timestamps
docker service logs -t web

# Limiter le nombre de lignes
docker service logs --tail 100 web

5 - Update a service​

Scaling​

# Changer le nombre de réplicas
docker service scale web=5

# Plusieurs services à la fois
docker service scale web=5 api=3 worker=10

Modify the configuration​

# Mettre à jour l'image
docker service update --image nginx:1.25 web

# Ajouter une variable d'environnement
docker service update --env-add DEBUG=true web

# Supprimer une variable
docker service update --env-rm DEBUG web

# Modifier les ressources
docker service update \
  --limit-cpu 0.5 \
  --limit-memory 512M \
  web

# Modifier le port publié
docker service update --publish-add 8080:80 web
docker service update --publish-rm 80:80 web

Rolling updates​

# Mise à jour progressive
docker service update \
  --update-parallelism 2 \
  --update-delay 10s \
  --image nginx:1.25 \
  web
OptionDescription
--update-parallelismNumber of tasks updated simultaneously
--update-delayDelay between each batch
--update-failure-actionAction on failure (pause, continue, rollback)
--update-orderOrder (stop-first, start-first)

6 - Rollback​

Return to the previous version​

# Rollback automatique
docker service rollback web

# Configurer le rollback automatique
docker service update \
  --update-failure-action rollback \
  --update-max-failure-ratio 0.3 \
  web

Rollback configuration​

docker service create --name web \
  --replicas 5 \
  --update-parallelism 2 \
  --update-delay 10s \
  --update-failure-action rollback \
  --rollback-parallelism 1 \
  --rollback-delay 5s \
  nginx:1.24

7 - Placement constraints​

Constraints on nodes​

# Uniquement sur les workers
docker service create --name web \
  --constraint 'node.role==worker' \
  nginx

# Uniquement sur un nœud spécifique
docker service create --name singleton \
  --constraint 'node.hostname==worker1' \
  myapp

# Basé sur les labels
docker service create --name web \
  --constraint 'node.labels.env==production' \
  nginx

# Plusieurs contraintes (AND)
docker service create --name web \
  --constraint 'node.role==worker' \
  --constraint 'node.labels.zone==eu-west' \
  nginx

Placement preferences​

# Préférer une distribution par zone
docker service create --name web \
  --replicas 6 \
  --placement-pref 'spread=node.labels.zone' \
  nginx
Zone A          Zone B          Zone C
┌─────────┐    ┌─────────┐    ┌─────────┐
│ web.1   │    │ web.3   │    │ web.5   │
│ web.2   │    │ web.4   │    │ web.6   │
└─────────┘    └─────────┘    └─────────┘

8 - Resources and limits​

Define limits​

docker service create --name api \
  --limit-cpu 0.5 \
  --limit-memory 256M \
  --reserve-cpu 0.25 \
  --reserve-memory 128M \
  node:18-alpine
OptionDescription
--limit-cpuMaximum CPU
--limit-memoryMaximum memory
--reserve-cpuGuaranteed (reserved) CPU
--reserve-memoryGuaranteed (reserved) memory

Impact on scheduling​

Node avec 4 CPU, 8 Go RAM

Service demandant reserve-cpu=1, reserve-memory=2G
→ Maximum 4 instances sur ce nœud

9 - Healthchecks​

Configure a healthcheck​

docker service create --name api \
  --health-cmd "curl -f http://localhost:3000/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  --health-start-period 60s \
  myapi:latest

Health states​

StateDescription
startingStartup period
healthyHealthcheck succeeded
unhealthyHealthcheck failed (restart)

10 - Remove a service​

# Supprimer un service
docker service rm web

# Supprimer plusieurs services
docker service rm web api worker

# Forcer sans confirmation
docker service rm $(docker service ls -q)

11 - Complete example​

Web application with database​

# Créer le réseau overlay
docker network create --driver overlay app-network

# Créer le service de base de données
docker service create --name db \
  --network app-network \
  --mount type=volume,source=pg-data,target=/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=myapp \
  --constraint 'node.labels.type==database' \
  postgres:15

# Créer le service API
docker service create --name api \
  --network app-network \
  --replicas 3 \
  -e DATABASE_URL=postgres://postgres:secret@db:5432/myapp \
  --constraint 'node.role==worker' \
  myapi:latest

# Créer le service web (frontend)
docker service create --name web \
  --network app-network \
  --replicas 3 \
  -p 80:80 \
  -e API_URL=http://api:3000 \
  myweb:latest

Command summary​

CommandDescription
docker service createCreate a service
docker service lsList services
docker service psView a service's tasks
docker service inspectDetails of a service
docker service logsLogs of a service
docker service scaleChange the number of replicas
docker service updateUpdate a service
docker service rollbackReturn to the previous version
docker service rmRemove a service
Key points
  • A service defines the desired state, Swarm maintains it
  • Tasks are the units of work (1 task = 1 container)
  • replicated mode for N instances, global for 1 per node
  • Constraints control the placement of tasks

Practical exercises​

  1. Create an nginx service with 5 replicas
  2. Scale the service to 10 replicas
  3. Update the image with a rolling update
  4. Test a rollback after an update

← Installation | Swarm networks →