Document ability to update a service's image #531
Conversation
| Each tag represents a digest, similar to a Git hash. Some tags, such as | ||
| `latest`, are updated occasionally to point to a new digest. Services are | ||
| constrained to run a specific digest of an image until you update the service | ||
| using `service update` with the `-image` flag, which is supported in Docker |
|
It might be useful to add some more details for the workflow here, or an example if you think suitable. In particular: will create a service with image The user can also create a service providing a digest, in which case it will be used directly with no resolution attempt. Additionally, if the image with a certain digest exists locally, Swarm will not pull it (moby/moby#28265), and just use the local copy. WDYT @mstanleyjones? |
| ### 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 Cloud |
There was a problem hiding this comment.
I believe this should be Docker Hub. Docker Cloud is a different product.
| When you run `service update` with the `-image` flag, a background function | ||
| called `ResolveTagToDigest` queries Docker Hub or your private Docker registry | ||
| for the digest the tag points to, and updates the service tasks to use that | ||
| digest. If the tag does not exist or the registry is not reachable, the service |
There was a problem hiding this comment.
We should not mention the name of the function from our source code.
When you create a service, or run `service update` and specify a new image with
the `--image` flag, Docker queries Docker Hub or your private Docker registry for
the digest the tag points to. It stores that digest on the service so that tasks will use
the image with this digest, ensuring that each node running the service uses the
same version of the image, even if the tag is updated while the service is running.
| for the digest the tag points to, and updates the service tasks to use that | ||
| digest. If the tag does not exist or the registry is not reachable, the service | ||
| continues running as before, still using the old image, and a warning is | ||
| shown. |
There was a problem hiding this comment.
If the tag does not exist or the registry is not reachable, the service probably won't work because nodes won't be able to pull the image. The exception is if the image already exists on the nodes that will run the service tasks, perhaps because it has been successfully pulled before.
There was a problem hiding this comment.
I was specifically talking about when you try to update the image and the updated version is not available. Wouldn't the service just keep running at its current image version in that case?
There was a problem hiding this comment.
The service still gets updated, but instead of getting an image reference with a digest in it, it gets one with a tag, like wordpress:latest. So it will only keep working if the node where it's running has an image called wordpress:latest. It may not have one, especially because it would have previously pulled something like wordpress@sha256:d98a7343ac750ffe387e3d514f8521ba69846c216778919b01414b8617cfb3d4.
|
Addressed all feedback except for the question above. |
|
@aaronlehmann PTAL again, tried to reword to catch the drift of what you were saying. |
| Engine 1.13 and higher. 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, a background function |
There was a problem hiding this comment.
Instead of "background function", let's say "Docker", "the service update operation", or something similar.
|
|
||
| - If the tag cannot be resolved to a locally cached image, the service | ||
| fails to update in the same way as if you attempt to create a new service | ||
| with an image that does not exist. |
There was a problem hiding this comment.
It might be helpful to note that this case is talking about whether the image is on the machine that tries to run the service. There may be cases where the manager has a local copy, but workers that try to run the service do not. There can also be cases where some workers have the image and some don't, so only some of them would be able to run the service until the problem is corrected.
|
@aaronlehmann @stevvooe @nishanttotla PTAL again and let me know if I have captured what happens if the tag can't be resolved. |
| or your local registry. You can force the service to use a specific version of | ||
| the image in a few different ways, depending on your desired outcome. | ||
|
|
||
| When you don't specify a tag, you get the latest version of an image, because |
There was a problem hiding this comment.
nit: latest tag rather than latest version.
latest doesn't have any special properties, so it's possible for it to be out of date. It's only the latest version by convention.
There was a problem hiding this comment.
I'd add some very strong warnings against leaving the state of your cluster to mercy of the latest tag.
|
|
||
| When you run `service update` with the `--image` flag, Docker | ||
| queries Docker Hub or your private Docker registry for the digest the tag points | ||
| to. and updates the service tasks to use that digest. |
|
|
||
| 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 local registry. You can force the service to use a specific version of |
There was a problem hiding this comment.
nit: we can remove local here.
| `latest`, `devel`, `yakkety`, and `16.04`. The image's tag name is resolved to | ||
| the specific digest it points to at the time of service creation. As an | ||
| alternative, you can specify the digest directly, and no digest resolution | ||
| occurs. |
There was a problem hiding this comment.
Can we explicitly show what an image string looks like, after resolution to digest? Such as ubuntu:latest@sha256:345kjhfkjaslf...?
There was a problem hiding this comment.
I did address this but not on this line, so Github didn't pick it up as resolved.
|
Feedback addressed. PTAL. |
| with `latest` is actually the newest or most up-to-date version. In general, it | ||
| is recommended that you choose a specific version of an image rather than | ||
| relying on `latest`. Otherwise, service tasks that deploy at different times may | ||
| use different versions of the image, and this may not be what you intend. |
There was a problem hiding this comment.
Did this text change from before? Sorry if I missed this earlier, but the messaging is confusing here. It's good to be clear that relying on latest isn't a good idea, but service tasks that deploy at different times may use different versions of the image is exactly what tag->digest resolution is meant to prevent. The only time this can fail is when the registry is unreachable or v1. Maybe it makes sense to specify that?
Especially since this is described below, so just a pointer to that might suffice.
| $ docker service create --name="myservice" ubuntu:latest | ||
| ``` | ||
|
|
||
| - If you specify a different tag, Docker resolves that tag to a digest, and uses |
There was a problem hiding this comment.
Let's be specific here Docker resolves -> agent resolves
| ``` | ||
|
|
||
| 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 |
There was a problem hiding this comment.
Again, this is only if the manager is able to resolve the tag to digest. Otherwise this is not guaranteed.
| ``` | ||
|
|
||
| **Note: Using `latest`** There is no guarantee that the version tagged | ||
| with `latest` is actually the newest or most up-to-date version. In general, it |
There was a problem hiding this comment.
The main reason to warn against latest is that over time, if image behind the latest tag updates, the service could end up with different versions. This text doesn't make that clear.
| 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 aThe following two commands are equivalent: |
| 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. |
There was a problem hiding this comment.
Let's just add a line here that this is particularly important for services that use mutable tags like latest, so that all service tasks use the same image.
|
OK, fixed the latest feedback! |
Fixes #528 Signed-off-by: Misty Stanley-Jones <misty@docker.com>
|
LGTM |
|
Merged! 🎉 |
Describe the proposed changes
Document the ability to update a service's image using
service update -imageUnreleased project version
Engine 1.13
Related issue
Fixes #528
Related issue or PR in another project
moby/moby#28173
Please take a look
@nishanttotla