github.com/panekj/cli@v0.0.0-20230304125325-467dd2f3797e/docs/reference/commandline/service_update.md (about) 1 # service update 2 3 <!---MARKER_GEN_START--> 4 Update a service 5 6 ### Options 7 8 | Name | Type | Default | Description | 9 |:----------------------------------------------|:------------------|:--------|:----------------------------------------------------------------------------------------------------| 10 | `--args` | `command` | | Service command args | 11 | `--cap-add` | `list` | | Add Linux capabilities | 12 | `--cap-drop` | `list` | | Drop Linux capabilities | 13 | `--config-add` | `config` | | Add or update a config file on a service | 14 | `--config-rm` | `list` | | Remove a configuration file | 15 | `--constraint-add` | `list` | | Add or update a placement constraint | 16 | `--constraint-rm` | `list` | | Remove a constraint | 17 | `--container-label-add` | `list` | | Add or update a container label | 18 | `--container-label-rm` | `list` | | Remove a container label by its key | 19 | `--credential-spec` | `credential-spec` | | Credential spec for managed service account (Windows only) | 20 | `-d`, `--detach` | | | Exit immediately instead of waiting for the service to converge | 21 | `--dns-add` | `list` | | Add or update a custom DNS server | 22 | `--dns-option-add` | `list` | | Add or update a DNS option | 23 | `--dns-option-rm` | `list` | | Remove a DNS option | 24 | `--dns-rm` | `list` | | Remove a custom DNS server | 25 | `--dns-search-add` | `list` | | Add or update a custom DNS search domain | 26 | `--dns-search-rm` | `list` | | Remove a DNS search domain | 27 | `--endpoint-mode` | `string` | | Endpoint mode (vip or dnsrr) | 28 | `--entrypoint` | `command` | | Overwrite the default ENTRYPOINT of the image | 29 | `--env-add` | `list` | | Add or update an environment variable | 30 | `--env-rm` | `list` | | Remove an environment variable | 31 | `--force` | | | Force update even if no changes require it | 32 | `--generic-resource-add` | `list` | | Add a Generic resource | 33 | `--generic-resource-rm` | `list` | | Remove a Generic resource | 34 | `--group-add` | `list` | | Add an additional supplementary user group to the container | 35 | `--group-rm` | `list` | | Remove a previously added supplementary user group from the container | 36 | `--health-cmd` | `string` | | Command to run to check health | 37 | `--health-interval` | `duration` | | Time between running the check (ms\|s\|m\|h) | 38 | `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | 39 | `--health-start-period` | `duration` | | Start period for the container to initialize before counting retries towards unstable (ms\|s\|m\|h) | 40 | `--health-timeout` | `duration` | | Maximum time to allow one check to run (ms\|s\|m\|h) | 41 | `--host-add` | `list` | | Add a custom host-to-IP mapping (`host:ip`) | 42 | `--host-rm` | `list` | | Remove a custom host-to-IP mapping (`host:ip`) | 43 | `--hostname` | `string` | | Container hostname | 44 | `--image` | `string` | | Service image tag | 45 | `--init` | | | Use an init inside each service container to forward signals and reap processes | 46 | [`--isolation`](#isolation) | `string` | | Service container isolation mode | 47 | `--label-add` | `list` | | Add or update a service label | 48 | `--label-rm` | `list` | | Remove a label by its key | 49 | `--limit-cpu` | `decimal` | | Limit CPUs | 50 | `--limit-memory` | `bytes` | `0` | Limit Memory | 51 | `--limit-pids` | `int64` | `0` | Limit maximum number of processes (default 0 = unlimited) | 52 | `--log-driver` | `string` | | Logging driver for service | 53 | `--log-opt` | `list` | | Logging driver options | 54 | `--max-concurrent` | `uint` | | Number of job tasks to run concurrently (default equal to --replicas) | 55 | [`--mount-add`](#mount-add) | `mount` | | Add or update a mount on a service | 56 | `--mount-rm` | `list` | | Remove a mount by its target path | 57 | [`--network-add`](#network-add) | `network` | | Add a network | 58 | `--network-rm` | `list` | | Remove a network | 59 | `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | 60 | `--no-resolve-image` | | | Do not query the registry to resolve image digest and supported platforms | 61 | `--placement-pref-add` | `pref` | | Add a placement preference | 62 | `--placement-pref-rm` | `pref` | | Remove a placement preference | 63 | [`--publish-add`](#publish-add) | `port` | | Add or update a published port | 64 | `--publish-rm` | `port` | | Remove a published port by its target port | 65 | `-q`, `--quiet` | | | Suppress progress output | 66 | `--read-only` | | | Mount the container's root filesystem as read only | 67 | `--replicas` | `uint` | | Number of tasks | 68 | `--replicas-max-per-node` | `uint64` | `0` | Maximum number of tasks per node (default 0 = unlimited) | 69 | `--reserve-cpu` | `decimal` | | Reserve CPUs | 70 | `--reserve-memory` | `bytes` | `0` | Reserve Memory | 71 | `--restart-condition` | `string` | | Restart when condition is met (`none`, `on-failure`, `any`) | 72 | `--restart-delay` | `duration` | | Delay between restart attempts (ns\|us\|ms\|s\|m\|h) | 73 | `--restart-max-attempts` | `uint` | | Maximum number of restarts before giving up | 74 | `--restart-window` | `duration` | | Window used to evaluate the restart policy (ns\|us\|ms\|s\|m\|h) | 75 | [`--rollback`](#rollback) | | | Rollback to previous specification | 76 | `--rollback-delay` | `duration` | `0s` | Delay between task rollbacks (ns\|us\|ms\|s\|m\|h) | 77 | `--rollback-failure-action` | `string` | | Action on rollback failure (`pause`, `continue`) | 78 | `--rollback-max-failure-ratio` | `float` | `0` | Failure rate to tolerate during a rollback | 79 | `--rollback-monitor` | `duration` | `0s` | Duration after each task rollback to monitor for failure (ns\|us\|ms\|s\|m\|h) | 80 | `--rollback-order` | `string` | | Rollback order (`start-first`, `stop-first`) | 81 | `--rollback-parallelism` | `uint64` | `0` | Maximum number of tasks rolled back simultaneously (0 to roll back all at once) | 82 | [`--secret-add`](#secret-add) | `secret` | | Add or update a secret on a service | 83 | `--secret-rm` | `list` | | Remove a secret | 84 | `--stop-grace-period` | `duration` | | Time to wait before force killing a container (ns\|us\|ms\|s\|m\|h) | 85 | `--stop-signal` | `string` | | Signal to stop the container | 86 | `--sysctl-add` | `list` | | Add or update a Sysctl option | 87 | `--sysctl-rm` | `list` | | Remove a Sysctl option | 88 | `-t`, `--tty` | | | Allocate a pseudo-TTY | 89 | `--ulimit-add` | `ulimit` | | Add or update a ulimit option | 90 | `--ulimit-rm` | `list` | | Remove a ulimit option | 91 | `--update-delay` | `duration` | `0s` | Delay between updates (ns\|us\|ms\|s\|m\|h) | 92 | `--update-failure-action` | `string` | | Action on update failure (`pause`, `continue`, `rollback`) | 93 | `--update-max-failure-ratio` | `float` | `0` | Failure rate to tolerate during an update | 94 | `--update-monitor` | `duration` | `0s` | Duration after each task update to monitor for failure (ns\|us\|ms\|s\|m\|h) | 95 | `--update-order` | `string` | | Update order (`start-first`, `stop-first`) | 96 | [`--update-parallelism`](#update-parallelism) | `uint64` | `0` | Maximum number of tasks updated simultaneously (0 to update all at once) | 97 | `-u`, `--user` | `string` | | Username or UID (format: <name\|uid>[:<group\|gid>]) | 98 | `--with-registry-auth` | | | Send registry authentication details to swarm agents | 99 | `-w`, `--workdir` | `string` | | Working directory inside the container | 100 101 102 <!---MARKER_GEN_END--> 103 104 ## Description 105 106 Updates a service as described by the specified parameters. The parameters are 107 the same as [`docker service create`](service_create.md). Refer to the description 108 there for further information. 109 110 Normally, updating a service will only cause the service's tasks to be replaced with new ones if a change to the 111 service requires recreating the tasks for it to take effect. For example, only changing the 112 `--update-parallelism` setting will not recreate the tasks, because the individual tasks are not affected by this 113 setting. However, the `--force` flag will cause the tasks to be recreated anyway. This can be used to perform a 114 rolling restart without any changes to the service parameters. 115 116 > **Note** 117 > 118 > This is a cluster management command, and must be executed on a swarm 119 > manager node. To learn about managers and workers, refer to the 120 > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the 121 > documentation. 122 123 ## Examples 124 125 ### Update a service 126 127 ```console 128 $ docker service update --limit-cpu 2 redis 129 ``` 130 131 ### <a name="update-parallelism"></a> Perform a rolling restart with no parameter changes 132 133 ```console 134 $ docker service update --force --update-parallelism 1 --update-delay 30s redis 135 ``` 136 137 In this example, the `--force` flag causes the service's tasks to be shut down 138 and replaced with new ones even though none of the other parameters would 139 normally cause that to happen. The `--update-parallelism 1` setting ensures 140 that only one task is replaced at a time (this is the default behavior). The 141 `--update-delay 30s` setting introduces a 30 second delay between tasks, so 142 that the rolling restart happens gradually. 143 144 ### <a name="mount-add"></a> Add or remove mounts (--mount-add, --mount-rm) 145 146 Use the `--mount-add` or `--mount-rm` options add or remove a service's bind mounts 147 or volumes. 148 149 The following example creates a service which mounts the `test-data` volume to 150 `/somewhere`. The next step updates the service to also mount the `other-volume` 151 volume to `/somewhere-else`volume, The last step unmounts the `/somewhere` mount 152 point, effectively removing the `test-data` volume. Each command returns the 153 service name. 154 155 - The `--mount-add` flag takes the same parameters as the `--mount` flag on 156 `service create`. Refer to the [volumes and bind mounts](service_create.md#mount) 157 section in the `service create` reference for details. 158 159 - The `--mount-rm` flag takes the `target` path of the mount. 160 161 ```console 162 $ docker service create \ 163 --name=myservice \ 164 --mount type=volume,source=test-data,target=/somewhere \ 165 nginx:alpine 166 167 myservice 168 169 $ docker service update \ 170 --mount-add type=volume,source=other-volume,target=/somewhere-else \ 171 myservice 172 173 myservice 174 175 $ docker service update --mount-rm /somewhere myservice 176 177 myservice 178 ``` 179 180 ### <a name="publish-add"></a> Add or remove published service ports (--publish-add, --publish-rm) 181 182 Use the `--publish-add` or `--publish-rm` flags to add or remove a published 183 port for a service. You can use the short or long syntax discussed in the 184 [docker service create](service_create.md#publish) 185 reference. 186 187 The following example adds a published service port to an existing service. 188 189 ```console 190 $ docker service update \ 191 --publish-add published=8080,target=80 \ 192 myservice 193 ``` 194 195 ### <a name="network-add"></a> Add or remove network (--network-add, --network-rm) 196 197 Use the `--network-add` or `--network-rm` flags to add or remove a network for 198 a service. You can use the short or long syntax discussed in the 199 [docker service create](service_create.md#network) 200 reference. 201 202 The following example adds a new alias name to an existing service already connected to network my-network: 203 204 ```console 205 $ docker service update \ 206 --network-rm my-network \ 207 --network-add name=my-network,alias=web1 \ 208 myservice 209 ``` 210 211 ### <a name="rollback"></a> Roll back to the previous version of a service (--rollback) 212 213 Use the `--rollback` option to roll back to the previous version of the service. 214 215 This will revert the service to the configuration that was in place before the most recent `docker service update` command. 216 217 The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration. 218 219 ```console 220 $ docker service update --replicas=5 web 221 222 web 223 224 $ docker service ls 225 226 ID NAME MODE REPLICAS IMAGE 227 80bvrzp6vxf3 web replicated 0/5 nginx:alpine 228 229 ``` 230 231 Roll back the `web` service... 232 233 ```console 234 $ docker service update --rollback web 235 236 web 237 238 $ docker service ls 239 240 ID NAME MODE REPLICAS IMAGE 241 80bvrzp6vxf3 web replicated 0/4 nginx:alpine 242 243 ``` 244 245 Other options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks: 246 247 ```console 248 $ docker service update \ 249 --rollback \ 250 --update-delay 0s 251 web 252 253 web 254 255 ``` 256 257 Services can also be set up to roll back to the previous version automatically 258 when an update fails. To set up a service for automatic rollback, use 259 `--update-failure-action=rollback`. A rollback will be triggered if the fraction 260 of the tasks which failed to update successfully exceeds the value given with 261 `--update-max-failure-ratio`. 262 263 The rate, parallelism, and other parameters of a rollback operation are 264 determined by the values passed with the following flags: 265 266 - `--rollback-delay` 267 - `--rollback-failure-action` 268 - `--rollback-max-failure-ratio` 269 - `--rollback-monitor` 270 - `--rollback-parallelism` 271 272 For example, a service set up with `--update-parallelism 1 --rollback-parallelism 3` 273 will update one task at a time during a normal update, but during a rollback, 3 274 tasks at a time will get rolled back. These rollback parameters are respected both 275 during automatic rollbacks and for rollbacks initiated manually using `--rollback`. 276 277 ### <a name="secret-add"></a> Add or remove secrets (--secret-add, --secret-rm) 278 279 Use the `--secret-add` or `--secret-rm` options add or remove a service's 280 secrets. 281 282 The following example adds a secret named `ssh-2` and removes `ssh-1`: 283 284 ```console 285 $ docker service update \ 286 --secret-add source=ssh-2,target=ssh-2 \ 287 --secret-rm ssh-1 \ 288 myservice 289 ``` 290 291 ### Update services using templates 292 293 Some flags of `service update` support the use of templating. 294 See [`service create`](service_create.md#create-services-using-templates) for the reference. 295 296 297 ### <a name="isolation"></a> Specify isolation mode on Windows (--isolation) 298 299 `service update` supports the same `--isolation` flag as `service create` 300 See [`service create`](service_create.md) for the reference. 301 302 ### Updating Jobs 303 304 When a service is created as a job, by setting its mode to `replicated-job` or 305 to `global-job` when doing `service create`, options for updating it are 306 limited. 307 308 Updating a Job immediately stops any Tasks that are in progress. The operation 309 creates a new set of Tasks for the job and effectively resets its completion 310 status. If any Tasks were running before the update, they are stopped, and new 311 Tasks are created. 312 313 Jobs cannot be rolled out or rolled back. None of the flags for configuring 314 update or rollback settings are valid with job modes. 315 316 To run a job again with the same parameters that it was run previously, it can 317 be force updated with the `--force` flag. 318 319 ## Related commands 320 321 * [service create](service_create.md) 322 * [service inspect](service_inspect.md) 323 * [service logs](service_logs.md) 324 * [service ls](service_ls.md) 325 * [service ps](service_ps.md) 326 * [service rm](service_rm.md) 327 * [service rollback](service_rollback.md) 328 * [service scale](service_scale.md)