Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท Services and Tasks

Service Create Options

A guided tour of docker service create: image, name, replicas, environment, mounts, networks, ports, update and restart flags, and how to inspect the result.

docker service create has more than seventy flags, but you will use a dozen of them again and again. This lesson organizes them by purpose, so that you can read any service definition and write your own. Later lessons go deeper into placement, resources, health and updates; here we build the overall picture.

The shape of the command

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

Everything after the image is the command and arguments that run inside the container, exactly as with docker run. Options come before the image.

Identity and scale

Flag Purpose
--name api Service name; also its DNS name on shared networks. If omitted Docker invents one.
--replicas 4 Desired number of tasks in replicated mode (default 1).
--mode global One task on every eligible node instead of a count.
--label tier=backend Label on the service, for your own organization and filters.
--container-label Label put on the containers (not on the service).

What runs in the container

Flag Purpose
--env KEY=value / -e Environment variable.
--env-file file Variables read from a file.
--workdir /app Working directory.
--user 1000:1000 Run as a non-root user.
--entrypoint Override the entrypoint.
--hostname, --init Container hostname; run a tiny init as PID 1 (reaps zombies).
--read-only Mount the root filesystem read-only.
--stop-signal, --stop-grace-period 30s How to ask the process to stop and how long to wait before killing it.
--cap-add, --cap-drop Linux capabilities.

Note: a few docker run flags are missing or different in swarm mode. For example --privileged is not available for services (use targeted capabilities), and bind-mounting uses --mount rather than -v.

Storage

CONSOLE
$ docker service create --name db \
    --mount type=volume,source=dbdata,target=/var/lib/postgresql/data \
    --mount type=bind,source=/etc/ssl/certs,target=/certs,readonly \
    --mount type=tmpfs,target=/tmp \
    postgres:17

Use --mount (it is explicit and has clear errors). A volume is created on the node where the task runs, with the local driver. If the task moves to another node, it gets an empty volume there. The consequences for databases are discussed in Operations.

Networking

Flag Purpose
--network backend Attach to an overlay network (repeatable).
--publish published=8080,target=80 Publish a port (routing mesh).
--endpoint-mode vip or dnsrr How the service name resolves (discovery).
--dns, --dns-search Resolver settings.

Placement and resources

--constraint, --placement-pref, --replicas-max-per-node, --limit-cpu, --limit-memory, --reserve-cpu, --reserve-memory: covered in the next lessons (placement, resources).

Updates, rollbacks and restarts

Flag Purpose
--update-parallelism 2 Tasks updated at the same time.
--update-delay 10s Pause between batches.
--update-failure-action pause|continue|rollback What to do when an update fails.
--rollback-parallelism, --rollback-delay The same for rollbacks.
--restart-condition none|on-failure|any When tasks restart.
--health-cmd and friends Health check (health checks).

Secrets, configs and registry

--secret, --config attach sensitive and plain configuration files (see Secrets and Configs). --with-registry-auth forwards your docker login credentials to the nodes so they can pull a private image. --no-resolve-image skips contacting the registry to pin the digest on the manager.

Other useful flags

  • --detach / -d: return at once instead of waiting for convergence.
  • --quiet / -q: print only the service ID.
  • --limit-pids, --ulimit: process limits.
  • --sysctl, --tty, --group: kernel parameters and other fine controls.

A realistic example

CONSOLE
$ docker service create \
    --name api \
    --replicas 3 \
    --network backend \
    --env APP_ENV=production \
    --limit-memory 256M --reserve-memory 128M \
    --constraint 'node.role==worker' \
    --update-parallelism 1 --update-delay 10s \
    --update-failure-action rollback \
    --health-cmd 'curl -fsS http://localhost:8000/health || exit 1' \
    --health-interval 15s \
    --with-registry-auth \
    registry.example.com/shop/api:1.4.2

Every flag maps to a field in the service spec that you can read back: docker service inspect api (JSON) or docker service inspect --pretty api. The same spec is what a Compose file's deploy: section produces.

Changing a service later

Nearly every flag has an update twin: docker service update --env-add FOO=bar, --env-rm, --mount-add, --network-add, --constraint-add, --limit-memory 512M, --publish-add, --image. An update creates new tasks, so it triggers a rolling replacement.

Stand-in: a service-spec builder

This stand-in assembles a command from a dictionary and checks two rules (replicas only in replicated mode; a name must be a valid DNS label). It shows the structure of a spec in code.

Python Stand-in: build a service command

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: spot the flag

A short drill that maps a need to the flag.

Python Stand-in: which flag?

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. Which flag lets worker nodes pull an image from a private registry you logged in to?

    --with-registry-auth sends your registry credentials with the service so nodes can pull the image.
  2. 2. Where does a named volume created by a service task live?

    The default local driver creates the volume on the node that runs the task, so it does not follow the task to another node.
  3. 3. What does changing a service with docker service update do to running containers?

    Tasks are immutable; any spec change results in replacement tasks (a rolling update).

Summary

  • Flags fall into identity, container, storage, network, placement, update and secret groups.
  • Use --mount, --publish published=...,target=... and --detach habitually.
  • Volumes are node-local with the default driver.
  • Every flag has an update counterpart; an update replaces tasks.

Next: Replicated and Global Services