From 1cf72c7944b15015f955ccd70b2b0120673dcd94 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Thu, 10 Nov 2016 16:53:39 -0800 Subject: [PATCH] Document ability to update a service's image Fixes #528 Signed-off-by: Misty Stanley-Jones --- engine/swarm/services.md | 129 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/engine/swarm/services.md b/engine/swarm/services.md index 40fe7c5c955..684fbe4deee 100644 --- a/engine/swarm/services.md +++ b/engine/swarm/services.md @@ -70,6 +70,135 @@ $ docker service create --name helloworld alpine ping docker.com 9uk4639qpg7npwf3fn2aasksr ``` +### Specify the image version the service should use + +When you create a service without specifying any details about the version of +the image to use, the service uses the latest version available in Docker Hub +or your registry. You can force the service to use a specific version of +the image in a few different ways, depending on your desired outcome. + +An image version can be expressed in several different ways: + +- If you specify a tag, the manager resolves that tag to a digest, and directs + workers to uses that version. + ```bash + $ docker service create --name="myservice" ubuntu:16.04 + ``` + + Some tags represent discrete releases, such as `ubuntu:16.04`. Tags like this + will almost always resolve to a stable digest over time. It is recommended + that you use this kind of tag when possible. + + Other types of tags, such as `latest` or `nightly`, may resolve to a new + digest often, depending on how often an image's author updates the tag. It is + not recommended to run services using a tag which is updated frequently, to + prevent different service replica tasks from using different image versions. + +- If you don't specify a version at all, by convention the image's `latest` tag + is resolved to a digest. The following two commands are equivalent: + ```bash + $ docker service create --name="myservice" ubuntu + + $ docker service create --name="myservice" ubuntu:latest + ``` + +- If you specify a digest directly, that exact version of the image is always + used. + ```bash + $ docker service create --name="myservice" ubuntu:16.04@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1 + ``` + +When you create a service, the swarm manager resolves the +image's tag to the specific digest it points to at the time of service creation. +If the manager is able to resolve the tag to a digest, worker nodes for that +service will use that specific digest unless the service is explicitly updated. +This feature is particularly important if you do use often-change tags such as +`latest`, to be sure that all service tasks use the same version of the image. + +If the manager is not able to resolve the tag to a digest, each worker +node is responsible for resolving the tag to a digest, and different nodes may +use different versions of the image. If this happens, a warning like the +following will be logged, substituting the placeholders for real information. + +```none +unable to pin image to digest: +``` + +To see an image's current digest, issue the command `docker inspect +:` and look for the `RepoDigests` line. The following is the current +digest for `ubuntu:latest` at the time this content was written. The output is +truncated for clarity. + +```bash +$ docker inspect ubuntu:latest +``` + +```json +"RepoDigests": [ + "ubuntu@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1" +], +``` + +After you create a service, its image is never updated unless you explicitly run +`docker service update` with the `--image` flag as described below. Other update +operations such as scaling the service, adding or removing networks or volumes, +renaming the service, or any other type of update operation do not update the +service's image. + +### Update a service's image after creation + +Each tag represents a digest, similar to a Git hash. Some tags, such as +`latest`, are updated often to point to a new digest. Others, such as +`ubuntu:16.04`, represent a released software version and are not expected to +update to point to a new digest often if at all. In Docker 1.13 and higher, when +you create a service, it is constrained to run a specific digest of an image +until you update the service using `service update` with the `--image` flag. If +you use an older version of Docker Engine, you must remove and re-create the +service to update its image. + +When you run `service update` with the `--image` flag, the swarm manager queries +Docker Hub or your private Docker registry for the digest the tag currently +points to and updates the service tasks to use that digest. + +Usually, the manager is able to resolve the tag to a new digest and the service +updates, redeploying each task to use the new image. If the manager is unable to +resolve the tag or some other problem occurs, the next two sections outline what +to expect. + +#### If the manager resolves the tag + +If the swarm manager can resolve the image tag to a digest, it instructs the +worker nodes to redeploy the tasks and use the image at that digest. + +- If a worker has cached the image at that digest, it uses it. + +- If not, it attempts to pull the image from Docker Hub or the private registry. + + - If it succeeds, the task is deployed using the new image. + + - If the worker fails to pull the image, the service fails to deploy on that + worker node. Docker tries again to deploy the task, possibly on a different + worker node. + +#### If the manager cannot resolve the tag + +If the swarm manager cannot resolve the image to a digest, all is not lost: + +- The manager instructs the worker nodes to redeploy the tasks using the image + at that tag. + +- If the worker has a locally cached image that resolves to that tag, it uses + that image. + +- If the worker does not have a locally cached image that resolves to the tag, + the worker tries to connect to Docker Hub or the private registry to pull the + image at that tag. + + - If this succeeds, the worker uses that image. + + - If this fails, the task fails to deploy and the manager tries again to deploy + the task, possibly on a different worker node. + ## Configure the runtime environment You can configure the following options for the runtime environment in the