docker service update

Estimated reading time: 11 minutes

Description

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.

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 true 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
--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.25+ 
Add or update 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
--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
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-elsevolume, 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 on service create. Refer to the volumes and bind mounts section in the service create reference for details.

  • The --mount-rm flag takes the target 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

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.