Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Services and Tasks

The Task Lifecycle

Follow a Swarm task from new to running to shutdown: every task state, what desired state means, how to read docker service ps and why failed tasks pile up.

A service is a plan. A task is one unit of that plan: a single container slot with a lifecycle of its own. Almost every Swarm debugging session starts with docker service ps, and reading it well means knowing the task states. This lesson walks through them.

What a task is

A task bundles three things: the service spec it was created from (image, command, limits), the slot it fills (the replica number, or the node for a global service) and the container that runs it. Tasks are created by the orchestrator, never by you, and never change after creation. When something is wrong, a task is replaced, not repaired.

Two states for every task

Each task has:

  • a desired state, set by the manager: running, ready or shutdown/remove, meaning what the cluster wants;
  • a current state, reported by the worker: what is actually happening.

docker service ps shows both, in the columns DESIRED STATE and CURRENT STATE.

The state sequence

A healthy task passes through these states in order:

State Meaning
new Created by the orchestrator.
pending Waiting for the allocator to prepare networks and for the scheduler to find a node.
assigned A node was chosen; the dispatcher is sending the task.
accepted The node's agent accepted the task.
preparing The node pulls the image and prepares mounts, secrets and configs.
ready Everything is prepared; the container exists but has not started.
starting The container is starting (and, with a health check, waiting for the first healthy result).
running The container is up.

And it ends in one of the terminal states:

State Meaning
complete The container exited with code 0 and will not be restarted.
shutdown The orchestrator asked it to stop (scale down, update, drain).
failed The container exited with an error, or failed health checks.
rejected The node refused or could not start it (missing path, image pull error, port clash).
remove Task is marked for removal.
orphaned Its node has been down too long; it will be cleaned up.
stateDiagram-v2
  [*] --> new
  new --> pending
  pending --> assigned
  assigned --> accepted
  accepted --> preparing
  preparing --> ready
  ready --> starting
  starting --> running
  running --> complete
  running --> failed
  running --> shutdown
  preparing --> rejected

The normal path is on top; terminal states are on the right. A terminal task is never revived: a new task takes its place.

Reading docker service ps

CONSOLE
$ docker service ps api
$ docker service ps --no-trunc api
$ docker service ps --filter desired-state=running api

Each row shows: ID, NAME (api.1 means slot 1 of the service), IMAGE, NODE, DESIRED STATE, CURRENT STATE (with age, like "Running 3 minutes ago") and ERROR. Names ending in \_ with an arrow (shown as \_ api.1) are previous tasks in the same slot, listed under the current one. When a container keeps crashing, you will see a stack of Failed tasks, each with a short error such as "task: non-zero exit (1)". --no-trunc prints the full error text.

By default Swarm keeps the last five tasks per slot (set with docker swarm update --task-history-limit). Old ones are pruned.

Restart behaviour

When a task fails, the restart policy decides whether a new task is started: --restart-condition any (default) restarts always, on-failure only after errors, none never. A delay (--restart-delay, default 5 seconds) and a limit (--restart-max-attempts, --restart-window) prevent tight loops. More in Health checks and restart policies.

Important distinction: restarting here means creating a new task, possibly on a different node, not restarting the same container.

Typical stories in the state column

  • Pending ... no suitable node (insufficient resources on 3 nodes): nothing can host it now. Free resources or relax requests.
  • Preparing for minutes: image pull is slow, or the registry credentials are missing (look for "No such image" or "pull access denied").
  • Rejected ... "No such image": image missing in registry or tag typo.
  • Starting then Failed over and over: the application exits. Run docker service logs api.
  • Shutdown with DESIRED Shutdown: normal result of an update or scale down.
  • Running but REPLICAS short: other tasks are failing; check them individually.

Stand-in: task state machine

This stand-in encodes the legal transitions of the diagram above. It refuses an illegal jump (for example from failed to running), mirroring the rule that terminal tasks are never revived.

Python Stand-in: task state machine

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: restart policy

The next editor applies none, on-failure and any to an exit code, then shows when Swarm would create a replacement task.

Python Stand-in: restart conditions

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.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. A task is in state 'pending' with the error 'no suitable node'. What does it mean?

    Pending tasks have not been assigned; typical causes are constraints, resource requests or platform mismatches.
  2. 2. What happens to a task that reached the 'failed' state?

    Tasks are immutable and terminal states are final. A replacement task takes over the slot.
  3. 3. What does the notation api.2 mean in docker service ps?

    The number is the replica slot; a new task in the same slot keeps the number.

Summary

  • A task is one immutable container slot with desired and current states.
  • Normal path: new, pending, assigned, accepted, preparing, ready, starting, running.
  • Terminal states: complete, shutdown, failed, rejected, remove, orphaned.
  • Restart means creating a new task, not reviving the old one.

Next: Placement Constraints and Preferences