18.2.2 Swarm Services

Swarm services are managed through a focused set of CLI commands covering their full practical lifecycle, creation, inspection, updating, rolling back, and removal, and knowing this command set directly is what turns the conceptual scheduling and desired-state behavior covered elsewhere into actual, day-to-day cluster operation.

Creating a service with common options

A service is created with a base image reference and any combination of options controlling replicas, ports, resources, and attached secrets or configs:

docker service create \
  --name my-api \
  --replicas 3 \
  --publish 80:80 \
  --limit-cpu 1 --limit-memory 512m \
  --secret db_password \
  my-api:1.4.2

Each of these flags corresponds directly to a field in the service's underlying specification, which can also be expressed declaratively through a stack file for anything beyond a quick, ad hoc service creation.

Inspecting service state and configuration

docker service inspect and docker service ps provide complementary views, the former showing the service's full declared specification, the latter showing the actual current state of each individual task:

docker service inspect my-api --pretty

docker service ps my-api

docker service logs my-api

docker service logs aggregates output across every task belonging to the service, which is generally more useful for understanding a service's overall behavior than checking individual container logs one replica at a time.

Updating a running service

Service updates apply incrementally and trigger the rolling update behavior covered elsewhere, and individual aspects of a service can be updated independently without needing to recreate it entirely:

docker service update --image my-api:1.5.0 my-api
docker service update --replicas 5 my-api
docker service update --env-add LOG_LEVEL=debug my-api

Each of these update commands modifies one specific aspect of the service's desired state, triggering reconciliation to bring the running tasks into alignment with whatever changed.

Rolling back a service update

Swarm retains the previous service specification specifically to support a direct rollback command, reverting to whatever configuration was in effect immediately before the most recent update, without needing to manually reconstruct and reapply the prior configuration:

docker service update --rollback my-api

docker service update --update-failure-action rollback --image my-api:1.5.0 my-api

The second form configures automatic rollback behavior directly: if the update itself fails partway through, Swarm reverts to the previous configuration automatically rather than leaving the service in a partially updated, potentially broken state requiring manual intervention.

Scaling a service

Adjusting replica count is available as both a dedicated, convenient shorthand and through the more general update command:

docker service scale my-api=5

docker service update --replicas 5 my-api

Both achieve the identical result; scale is simply a more concise, purpose-specific convenience for this one particular, common operation.

Removing a service

Removing a service stops and removes every one of its tasks across the cluster in one operation, which is distinct from scaling a service to zero replicas, since removal also deletes the service's own definition entirely rather than leaving it at zero replicas and able to be scaled back up later:

docker service rm my-api

docker service scale my-api=0

Choosing between these depends on intent: scaling to zero is appropriate for a temporary pause where the service definition itself should remain intact for a later return to active replicas; removal is appropriate when the service is genuinely no longer needed at all.

Attaching secrets and configs to a service

Secrets and configs, covered conceptually elsewhere, are attached to a service directly at creation or through an update, making them available to the service's tasks as mounted files:

docker service create --secret db_password --config app_config my-api

docker service update --secret-add new_secret --secret-rm old_secret my-api

Updating which secrets or configs are attached triggers the same rolling update behavior as any other service specification change, replacing tasks gradually to pick up the new attachment rather than affecting every running task simultaneously.

Listing and filtering services across a cluster

For a cluster running many services, filtering the service list by name pattern or label narrows down what is displayed to exactly what is currently relevant:

docker service ls --filter "name=api"
docker service ls --filter "label=team=payments"

Common mistakes

• Checking individual container logs one replica at a time rather than using docker service logs to see aggregated output across every task belonging to a service.
• Not configuring an automatic rollback failure action, leaving a failed update to potentially strand the service in a partially updated, broken state requiring manual intervention to recover.
• Confusing scaling a service to zero replicas with removing it entirely, when the two have meaningfully different implications for whether the service definition itself persists.
• Manually attempting to reconstruct a previous service configuration after a bad update rather than using the direct, built-in rollback command.
• Not using label or name filters when listing services on a cluster running many of them, scrolling through an unfiltered, unwieldy full list instead.

Swarm services are managed through a focused, practical command set, create, inspect, update, scale, roll back, and remove, each corresponding directly to the underlying desired-state and scheduling concepts, and fluency with this specific command set is what turns the conceptual model into actual, confident day-to-day cluster operation.