Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 38 ยท Getting Started

Your First Swarm Service

Create, inspect, scale and remove your first Docker Swarm service with docker service commands, and watch tasks spread across the nodes of your cluster.

With a swarm running, you can finally do the thing it exists for: run a service. A service is a named, replicated workload. In this lesson you will create a web service, look at where its tasks landed, scale it up and down, and remove it. Commands are shown read-only; run them on a manager of your practice cluster.

Creating a service

CONSOLE
$ docker service create --name web --replicas 3 --publish published=8080,target=80 nginx:1.27

Read it from left to right:

  • docker service create is the swarm counterpart of docker run.
  • --name web gives the service a name that other services can use as a DNS name.
  • --replicas 3 is the desired number of tasks.
  • --publish published=8080,target=80 makes port 80 of the containers reachable on port 8080 of every node (the routing mesh, see Routing mesh).
  • nginx:1.27 is the image. Every node that gets a task pulls it on its own.

Docker prints the service ID and then follows the rollout, waiting until the replicas converge. Add --detach (or -d) to return immediately.

Listing services

CONSOLE
$ docker service ls

The columns are ID, NAME, MODE (replicated), REPLICAS (shown like 3/3: running over desired), IMAGE and PORTS. If you see 1/3, two tasks are not running yet, perhaps still pulling the image.

Where did the tasks go?

CONSOLE
$ docker service ps web

Each row is one task: an ID such as web.1, the image, the node it was scheduled on, the desired state, the current state and any error. With three replicas on three nodes, the default scheduler spreads them across the nodes. You can see the same information per node:

CONSOLE
$ docker node ps worker1

On a manager node, docker ps shows only containers running on that node, whereas docker service ps shows tasks cluster-wide.

Testing the service

Because of the routing mesh, you can use any node's IP:

CONSOLE
$ curl http://192.168.56.12:8080

even if no web task runs on that node. The request is forwarded to a task elsewhere.

Scaling

CONSOLE
$ docker service scale web=5
$ docker service scale web=2

or equivalently docker service update --replicas 5 web. Scaling down removes tasks; the scheduler picks which ones. Scaling up adds tasks wherever they fit.

Inspecting and reading logs

CONSOLE
$ docker service inspect --pretty web
$ docker service logs web
$ docker service logs --follow --tail 20 web

--pretty prints a human-readable summary. service logs merges the output of all tasks of the service, each line prefixed with the task name, which is very handy compared with visiting each node.

Updating

CONSOLE
$ docker service update --image nginx:1.27.1 web

Swarm replaces the tasks one by one (the default update parallelism is 1). You will tune this in Scaling and Updates.

Removing

CONSOLE
$ docker service rm web

All tasks stop and their containers are removed. Images stay on the nodes until pruned.

Watching self-healing

Find the container of one task, kill it on its node with docker kill, and run docker service ps web again. You will see the old task in state Failed and a new task that Swarm started. The history is kept so you can diagnose crashes. Task lifecycle explains the states.

flowchart LR
  A["web.1 on node A: running"] -->|container killed| B["web.1 failed"]
  B --> C["Orchestrator: 2 of 3, need 3"]
  C --> D["new web.1 scheduled"]

The scheduler restores the replica count without your involvement.

Stand-in: spread replicas across nodes

The scheduler's default is to place each new task on the node that currently runs the fewest tasks of that service. Try different replica counts and nodes in this simulation (a stand-in of the idea, not the real scheduler, which also considers resources and constraints).

Python Stand-in: default spreading

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: parse the REPLICAS column

3/3 means running over desired. This helper decides what is wrong, the kind of thing you do when reading docker service ls quickly.

Python Stand-in: reading REPLICAS

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common beginner mistakes

  • Using docker run and expecting swarm behaviour. Containers started with docker run are not part of any service and are not healed by Swarm.
  • Publishing a port that is already used on a node. In ingress mode the port is reserved on every node, so a host process using 8080 makes the service fail to publish.
  • Private images without credentials. Pass --with-registry-auth so nodes can pull from your registry, as you will see later.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What does REPLICAS 2/3 in docker service ls mean?

    The first number is running tasks, the second is the desired count.
  2. 2. Which command shows on which node each task runs?

    docker service ps lists all tasks of the service with their nodes. docker ps shows only the local node.
  3. 3. How can you reach a published service?

    The routing mesh listens on the published port on every node and forwards to a running task.

Summary

  • docker service create defines desired state; --replicas sets the count.
  • docker service ls, ps, inspect and logs show the state of the whole cluster.
  • docker service scale and update change a running service.
  • Killing a container triggers a replacement task.

Next: Managers and Workers