Document ability to update a service's image

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 <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.
+
+```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