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