Image Digest Resolution, Service Updates, and Error Handling

$ 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 when creating service tasks. ```console $ docker service create \ --name="myservice" \ ubuntu:16.04@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1 ``` When you create a service, the image's tag is resolved to the specific digest the tag points to **at the time of service creation**. Worker nodes for that service use that specific digest forever unless the service is explicitly updated. This feature is particularly important if you do use often-changing tags such as `latest`, because it ensures that all service tasks use the same version of the image. > [!NOTE]> > > If [content trust](../security/trust/_index.md) is > enabled, the client actually resolves the image's tag to a digest before > contacting the swarm manager, to verify that the image is signed. > Thus, if you use content trust, the swarm manager receives the request > pre-resolved. In this case, if the client cannot resolve the image to a > digest, the request fails. If the manager can't 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 is logged, substituting the placeholders for real information. ```none unable to pin image <IMAGE-NAME> to digest: <REASON> ``` To see an image's current digest, issue the command `docker inspect <IMAGE>:<TAG>` 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. ```console $ 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. When you create a service, it is constrained to create tasks using a specific digest of an image until you update the service using `service update` with the `--image` flag. 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. > [!NOTE] > > If you use [content trust](../security/trust/_index.md), the Docker > client resolves image and the swarm manager receives the image and digest, > rather than a tag. Usually, the manager can resolve the tag to a new digest and the service updates, redeploying each task to use the new image. If the manager can't 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.

This section discusses how Docker resolves image tags to digests during service creation and updates, including the role of content trust. It explains the consequences of the manager's inability to resolve a tag to a digest, leading to potential image version discrepancies across worker nodes. It also covers how to update a service's image using `docker service update --image`, emphasizing that other update operations do not affect the service's image. The section details the process of image update and the error handling mechanisms when the manager can't resolve the tag, affecting task deployment and redeployment on worker nodes.