docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1065 from mstanleyjones/service_create_with_content_trust 

Add info about image resolution with content trust
This commit is contained in:
Misty Stanley-Jones 2017-01-12 15:47:56 -08:00 committed by Misty Stanley-Jones
parent 0f68d0a37a 6415ff6660
commit 32d07fe77c
1 changed files with 52 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
engine/swarm/services.md
View File

@ -107,14 +107,17 @@ flag. For more information, see
### Specify the image version the service should use ### Specify the image version the service should use
When you create a service without specifying any details about the version of 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 the image to use, the service uses the version tagged with the `latest` tag.
or your registry. You can force the service to use a specific version of You can force the service to use a specific version of the image in a few
the image in a few different ways, depending on your desired outcome. different ways, depending on your desired outcome.
An image version can be expressed in several different ways: 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 - If you specify a tag, the manager (or the Docker client, if you use
workers to uses that version. [content trust](#image_resolution_with_trust)) resolves that tag to a digest.
When the request to create a container task is received on a worker node, the
worker node only sees the digest, not the tag.
```bash ```bash
$ docker service create --name="myservice" ubuntu:16.04 $ docker service create --name="myservice" ubuntu:16.04
``` ```
@ -129,7 +132,11 @@ An image version can be expressed in several different ways:
prevent different service replica tasks from using different image versions. 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 - 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: is resolved to a digest. Workers use the image at this digest when creating
the service task.
Thus, the following two commands are equivalent:
```bash ```bash
$ docker service create --name="myservice" ubuntu $ docker service create --name="myservice" ubuntu
@ -137,17 +144,27 @@ An image version can be expressed in several different ways:
``` ```
- If you specify a digest directly, that exact version of the image is always - If you specify a digest directly, that exact version of the image is always
used. used when creating service tasks.
```bash ```bash
$ docker service create --name="myservice" ubuntu:16.04@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1 $ docker service create \
--name="myservice" \
ubuntu:16.04@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1
``` ```
When you create a service, the swarm manager resolves the When you create a service, the image's tag is resolved to the specific digest
image's tag to the specific digest it points to at the time of service creation. the tag points to **at the time of service creation**. Worker nodes for that
If the manager is able to resolve the tag to a digest, worker nodes for that service will use that specific digest forever unless the service is explicitly
service will use that specific digest unless the service is explicitly updated. updated. This feature is particularly important if you do use often-changing tags
This feature is particularly important if you do use often-change tags such as such as `latest`, because it ensures that all service tasks use the same version
`latest`, to be sure that all service tasks use the same version of the image. of the image.
> **Note**: If [content trust](security/trust/content_trust.md) is enabled, the
> client actually resolves the image's tag to a digest before contacting the
> swarm manager, in order 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.
{: id="image_resolution_with_trust" }
If the manager is not able to resolve the tag to a digest, each worker 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 node is responsible for resolving the tag to a digest, and different nodes may
@ -155,13 +172,13 @@ use different versions of the image. If this happens, a warning like the
following will be logged, substituting the placeholders for real information. following will be logged, substituting the placeholders for real information.
```none ```none
unable to pin image <image_name> to digest: <reason> unable to pin image <IMAGE-NAME> to digest: <REASON>
``` ```
To see an image's current digest, issue the command `docker inspect To see an image's current digest, issue the command
<image>:<tag>` and look for the `RepoDigests` line. The following is the current `docker inspect <IMAGE>:<TAG>` and look for the `RepoDigests` line. The
digest for `ubuntu:latest` at the time this content was written. The output is following is the current digest for `ubuntu:latest` at the time this content
truncated for clarity. was written. The output is truncated for clarity.
```bash ```bash
$ docker inspect ubuntu:latest $ docker inspect ubuntu:latest
@ -185,15 +202,19 @@ 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 `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 `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 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 you create a service, it is constrained to create tasks using a specific digest\
until you update the service using `service update` with the `--image` flag. If of an image until you update the service using `service update` with the
you use an older version of Docker Engine, you must remove and re-create the `--image` flag. If you use an older version of Docker Engine, you must remove
service to update its image. and re-create the service to update its image.
When you run `service update` with the `--image` flag, the swarm manager queries 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 Docker Hub or your private Docker registry for the digest the tag currently
points to and updates the service tasks to use that digest. points to and updates the service tasks to use that digest.
> **Note**: If you use [content trust](#image_resolution_with_trust), the Docker
> client resolves image and the swarm manager receives the image and digest,
> rather than a tag.
Usually, the manager is able to resolve the tag to a new digest and the service 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 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 resolve the tag or some other problem occurs, the next two sections outline what
@ -246,7 +267,10 @@ the number of replica tasks you want to start using the `--replicas` flag. For
example, to start a replicated nginx service with 3 replica tasks: example, to start a replicated nginx service with 3 replica tasks:
```bash ```bash
$ docker service create --name my_web --replicas 3 nginx $ docker service create \
--name my_web \
--replicas 3 \
nginx
``` ```
To start a global service on each available node, pass `--mode global` to To start a global service on each available node, pass `--mode global` to
@ -255,7 +279,10 @@ places a task for the global service on the new node. For example to start a
service that runs alpine on every node in the swarm: service that runs alpine on every node in the swarm:
```bash ```bash
$ docker service create --name myservice --mode global alpine top $ docker service create \
--name myservice \
--mode global \
alpine top
``` ```
Service constraints let you set criteria for a node to meet before the scheduler Service constraints let you set criteria for a node to meet before the scheduler