Handling Image Resolution Failure and Publishing Service Ports

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. #### 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. ### Publish ports When you create a swarm service, you can publish that service's ports to hosts outside the swarm in two ways: - [You can rely on the routing mesh](#publish-a-services-ports-using-the-routing-mesh). When you publish a service port, the swarm makes the service accessible at the target port on every node, regardless of whether there is a task for the service running on that node or not. This is less complex and is the right choice for many types of services. - [You can publish a service task's port directly on the swarm node](#publish-a-services-ports-directly-on-the-swarm-node) where that service is running. This bypasses the routing mesh and provides the maximum flexibility, including the ability for you to develop your own routing framework. However, you are responsible for keeping track of where each task is running and routing requests to the tasks, and load-balancing across the nodes. Keep reading for more information and use cases for each of these methods. #### Publish a service's ports using the routing mesh To publish a service's ports externally to the swarm, use the `--publish <PUBLISHED-PORT>:<SERVICE-PORT>` flag. The swarm makes the service accessible at the published port on every swarm node. If an external host connects to that port on any swarm node, the routing mesh routes it to a task. The external host does not need to know the IP addresses or internally-used ports of the service tasks to interact with the service. When a user or process connects to a service, any worker node running a service task may respond. For more details about swarm service networking, see [Manage swarm service networks](networking.md). ##### Example: Run a three-task Nginx service on 10-node swarm Imagine that you have a 10-node swarm, and you deploy an Nginx service running three tasks on a 10-node swarm: ```console $ docker service create --name my_web \ --replicas 3 \ --publish published=8080,target=80 \ nginx ``` Three tasks run on up to three nodes. You don't need to know which nodes are running the tasks; connecting to port 8080 on any of the 10 nodes connects you to one of the three `nginx` tasks. You can test this using `curl`.

This section outlines what happens when the swarm manager cannot resolve an image tag to a digest during a service update. In such cases, worker nodes attempt to pull the image based on the tag, using locally cached versions if available. Failure to pull the image results in task deployment failure. The section then discusses two methods of publishing service ports in a swarm: using the routing mesh, which makes the service accessible on every node, and directly publishing a service task's port on the node it's running on, bypassing the routing mesh and offering greater flexibility but requiring manual task tracking and load balancing. An example demonstrates publishing an Nginx service's ports using the routing mesh on a 10-node swarm.