docker service update
Estimated reading time: 16 minutesDescription
Update a service
API 1.24+
The client and daemon API must both be at least
1.24
to use this command. Use the docker version
command on the client to check
your client and daemon API versions.
Swarm This command works with the Swarm orchestrator.
Usage
docker service update [OPTIONS] SERVICE
Options
Name, shorthand | Default | Description |
--args |
Service command args | |
--config-add |
API 1.30+ Add or update a config file on a service |
|
--config-rm |
API 1.30+ Remove a configuration file |
|
--constraint-add |
Add or update a placement constraint | |
--constraint-rm |
Remove a constraint | |
--container-label-add |
Add or update a container label | |
--container-label-rm |
Remove a container label by its key | |
--credential-spec |
API 1.29+ Credential spec for managed service account (Windows only) |
|
--detach , -d |
API 1.29+ Exit immediately instead of waiting for the service to converge |
|
--dns-add |
API 1.25+ Add or update a custom DNS server |
|
--dns-option-add |
API 1.25+ Add or update a DNS option |
|
--dns-option-rm |
API 1.25+ Remove a DNS option |
|
--dns-rm |
API 1.25+ Remove a custom DNS server |
|
--dns-search-add |
API 1.25+ Add or update a custom DNS search domain |
|
--dns-search-rm |
API 1.25+ Remove a DNS search domain |
|
--endpoint-mode |
Endpoint mode (vip or dnsrr) | |
--entrypoint |
Overwrite the default ENTRYPOINT of the image | |
--env-add |
Add or update an environment variable | |
--env-rm |
Remove an environment variable | |
--force |
API 1.25+ Force update even if no changes require it |
|
--generic-resource-add |
Add a Generic resource | |
--generic-resource-rm |
Remove a Generic resource | |
--group-add |
API 1.25+ Add an additional supplementary user group to the container |
|
--group-rm |
API 1.25+ Remove a previously added supplementary user group from the container |
|
--health-cmd |
API 1.25+ Command to run to check health |
|
--health-interval |
API 1.25+ Time between running the check (ms|s|m|h) |
|
--health-retries |
API 1.25+ Consecutive failures needed to report unhealthy |
|
--health-start-period |
API 1.29+ Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) |
|
--health-timeout |
API 1.25+ Maximum time to allow one check to run (ms|s|m|h) |
|
--host-add |
API 1.32+ Add a custom host-to-IP mapping (host:ip) |
|
--host-rm |
API 1.25+ Remove a custom host-to-IP mapping (host:ip) |
|
--hostname |
API 1.25+ Container hostname |
|
--image |
Service image tag | |
--init |
API 1.37+ Use an init inside each service container to forward signals and reap processes |
|
--isolation |
API 1.35+ Service container isolation mode |
|
--label-add |
Add or update a service label | |
--label-rm |
Remove a label by its key | |
--limit-cpu |
Limit CPUs | |
--limit-memory |
Limit Memory | |
--log-driver |
Logging driver for service | |
--log-opt |
Logging driver options | |
--mount-add |
Add or update a mount on a service | |
--mount-rm |
Remove a mount by its target path | |
--network-add |
API 1.29+ Add a network |
|
--network-rm |
API 1.29+ Remove a network |
|
--no-healthcheck |
API 1.25+ Disable any container-specified HEALTHCHECK |
|
--no-resolve-image |
API 1.30+ Do not query the registry to resolve image digest and supported platforms |
|
--placement-pref-add |
API 1.28+ Add a placement preference |
|
--placement-pref-rm |
API 1.28+ Remove a placement preference |
|
--publish-add |
Add or update a published port | |
--publish-rm |
Remove a published port by its target port | |
--quiet , -q |
Suppress progress output | |
--read-only |
API 1.28+ Mount the container’s root filesystem as read only |
|
--replicas |
Number of tasks | |
--reserve-cpu |
Reserve CPUs | |
--reserve-memory |
Reserve Memory | |
--restart-condition |
Restart when condition is met (“none”|”on-failure”|”any”) | |
--restart-delay |
Delay between restart attempts (ns|us|ms|s|m|h) | |
--restart-max-attempts |
Maximum number of restarts before giving up | |
--restart-window |
Window used to evaluate the restart policy (ns|us|ms|s|m|h) | |
--rollback |
API 1.25+ Rollback to previous specification |
|
--rollback-delay |
API 1.28+ Delay between task rollbacks (ns|us|ms|s|m|h) |
|
--rollback-failure-action |
API 1.28+ Action on rollback failure (“pause”|”continue”) |
|
--rollback-max-failure-ratio |
API 1.28+ Failure rate to tolerate during a rollback |
|
--rollback-monitor |
API 1.28+ Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) |
|
--rollback-order |
API 1.29+ Rollback order (“start-first”|”stop-first”) |
|
--rollback-parallelism |
API 1.28+ Maximum number of tasks rolled back simultaneously (0 to roll back all at once) |
|
--secret-add |
API 1.25+ Add or update a secret on a service |
|
--secret-rm |
API 1.25+ Remove a secret |
|
--stop-grace-period |
Time to wait before force killing a container (ns|us|ms|s|m|h) | |
--stop-signal |
API 1.28+ Signal to stop the container |
|
--tty , -t |
API 1.25+ Allocate a pseudo-TTY |
|
--update-delay |
Delay between updates (ns|us|ms|s|m|h) | |
--update-failure-action |
Action on update failure (“pause”|”continue”|”rollback”) | |
--update-max-failure-ratio |
API 1.25+ Failure rate to tolerate during an update |
|
--update-monitor |
API 1.25+ Duration after each task update to monitor for failure (ns|us|ms|s|m|h) |
|
--update-order |
API 1.29+ Update order (“start-first”|”stop-first”) |
|
--update-parallelism |
Maximum number of tasks updated simultaneously (0 to update all at once) | |
--user , -u |
Username or UID (format: <name|uid>[:<group|gid>]) | |
--with-registry-auth |
Send registry authentication details to swarm agents | |
--workdir , -w |
Working directory inside the container |
Parent command
Command | Description |
---|---|
docker service | Manage services |
Related commands
Command | Description |
docker service create | Create a new service |
docker service inspect | Display detailed information on one or more services |
docker service logs | Fetch the logs of a service or task |
docker service ls | List services |
docker service ps | List the tasks of one or more services |
docker service rm | Remove one or more services |
docker service rollback | Revert changes to a service’s configuration |
docker service scale | Scale one or multiple replicated services |
docker service update | Update a service |
Extended description
Updates a service as described by the specified parameters. This command has to be run targeting a manager node.
The parameters are the same as docker service create
. Please look at the description there
for further information.
Normally, updating a service will only cause the service’s tasks to be replaced with new ones if a change to the
service requires recreating the tasks for it to take effect. For example, only changing the
--update-parallelism
setting will not recreate the tasks, because the individual tasks are not affected by this
setting. However, the --force
flag will cause the tasks to be recreated anyway. This can be used to perform a
rolling restart without any changes to the service parameters.
Examples
Update a service
$ docker service update --limit-cpu 2 redis
Perform a rolling restart with no parameter changes
$ docker service update --force --update-parallelism 1 --update-delay 30s redis
In this example, the --force
flag causes the service’s tasks to be shut down
and replaced with new ones even though none of the other parameters would
normally cause that to happen. The --update-parallelism 1
setting ensures
that only one task is replaced at a time (this is the default behavior). The
--update-delay 30s
setting introduces a 30 second delay between tasks, so
that the rolling restart happens gradually.
Add or remove mounts
Use the --mount-add
or --mount-rm
options add or remove a service’s bind mounts
or volumes.
The following example creates a service which mounts the test-data
volume to
/somewhere
. The next step updates the service to also mount the other-volume
volume to /somewhere-else
volume, The last step unmounts the /somewhere
mount
point, effectively removing the test-data
volume. Each command returns the
service name.
-
The
--mount-add
flag takes the same parameters as the--mount
flag onservice create
. Refer to the volumes and bind mounts section in theservice create
reference for details. -
The
--mount-rm
flag takes thetarget
path of the mount.
$ docker service create \
--name=myservice \
--mount \
type=volume,source=test-data,target=/somewhere \
nginx:alpine \
myservice
myservice
$ docker service update \
--mount-add \
type=volume,source=other-volume,target=/somewhere-else \
myservice
myservice
$ docker service update --mount-rm /somewhere myservice
myservice
Add or remove published service ports
Use the --publish-add
or --publish-rm
flags to add or remove a published
port for a service. You can use the short or long syntax discussed in the
docker service create
reference.
The following example adds a published service port to an existing service.
$ docker service update \
--publish-add published=8080,target=80 \
myservice
Add or remove network
Use the --network-add
or --network-rm
flags to add or remove a network for
a service. You can use the short or long syntax discussed in the
docker service create
reference.
The following example adds a new alias name to an existing service already connected to network my-network:
$ docker service update \
--network-rm my-network \
--network-add name=my-network,alias=web1 \
myservice
Roll back to the previous version of a service
Use the --rollback
option to roll back to the previous version of the service.
This will revert the service to the configuration that was in place before the most recent docker service update
command.
The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration.
$ docker service update --replicas=5 web
web
$ docker service ls
ID NAME MODE REPLICAS IMAGE
80bvrzp6vxf3 web replicated 0/5 nginx:alpine
Roll back the web
service...
$ docker service update --rollback web
web
$ docker service ls
ID NAME MODE REPLICAS IMAGE
80bvrzp6vxf3 web replicated 0/4 nginx:alpine
Other options can be combined with --rollback
as well, for example, --update-delay 0s
to execute the rollback without a delay between tasks:
$ docker service update \
--rollback \
--update-delay 0s
web
web
Services can also be set up to roll back to the previous version automatically
when an update fails. To set up a service for automatic rollback, use
--update-failure-action=rollback
. A rollback will be triggered if the fraction
of the tasks which failed to update successfully exceeds the value given with
--update-max-failure-ratio
.
The rate, parallelism, and other parameters of a rollback operation are determined by the values passed with the following flags:
--rollback-delay
--rollback-failure-action
--rollback-max-failure-ratio
--rollback-monitor
--rollback-parallelism
For example, a service set up with --update-parallelism 1 --rollback-parallelism 3
will update one task at a time during a normal update, but during a rollback, 3
tasks at a time will get rolled back. These rollback parameters are respected both
during automatic rollbacks and for rollbacks initiated manually using --rollback
.
Add or remove secrets
Use the --secret-add
or --secret-rm
options add or remove a service’s
secrets.
The following example adds a secret named ssh-2
and removes ssh-1
:
$ docker service update \
--secret-add source=ssh-2,target=ssh-2 \
--secret-rm ssh-1 \
myservice
Update services using templates
Some flags of service update
support the use of templating.
See service create
for the reference.
Specify isolation mode (Windows)
service update
supports the same --isolation
flag as service create
See service create
for the reference.