diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 9a03c516..9ba7286a 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -192,6 +192,10 @@ Or FROM : +Or + + FROM @ + The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image) for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as its first instruction. The image can be any valid image – it is especially easy @@ -204,8 +208,9 @@ to start by **pulling an image** from the [*Public Repositories*]( multiple images. Simply make a note of the last image ID output by the commit before each new `FROM` command. -If no `tag` is given to the `FROM` instruction, `latest` is assumed. If the -used tag does not exist, an error will be returned. +The `tag` or `digest` values are optional. If you omit either of them, the builder +assumes a `latest` by default. The builder returns an error if it cannot match +the `tag` value. ## MAINTAINER diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 4ce50a7b..c1fcd3ea 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -1112,7 +1112,9 @@ To see how the `docker:latest` image was built: List images -a, --all=false Show all images (default hides intermediate images) + --digests=false Show digests -f, --filter=[] Filter output based on conditions provided + --help=false Print usage --no-trunc=false Don't truncate output -q, --quiet=false Only show numeric IDs @@ -1161,6 +1163,22 @@ uses up the `VIRTUAL SIZE` listed only once. tryout latest 2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB 5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB +#### Listing image digests + +Images that use the v2 or later format have a content-addressable identifier +called a `digest`. As long as the input used to generate the image is +unchanged, the digest value is predictable. To list image digest values, use +the `--digests` flag: + + $ sudo docker images --digests | head + REPOSITORY TAG DIGEST IMAGE ID CREATED VIRTUAL SIZE + localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB + +When pushing or pulling to a 2.0 registry, the `push` or `pull` command +output includes the image digest. You can `pull` using a digest value. You can +also reference by digest in `create`, `run`, and `rmi` commands, as well as the +`FROM` image reference in a Dockerfile. + #### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more @@ -1563,6 +1581,10 @@ use `docker pull`: $ sudo docker pull debian:testing # will pull the image named debian:testing and any intermediate # layers it is based on. + $ sudo docker pull debian@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + # will pull the image from the debian repository with the digest + # sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + # and any intermediate layers it is based on. # (Typically the empty `scratch` image, a MAINTAINER layer, # and the un-tarred base). $ sudo docker pull --all-tags centos @@ -1634,9 +1656,9 @@ deleted. #### Removing tagged images -Images can be removed either by their short or long IDs, or their image -names. If an image has more than one name, each of them needs to be -removed before the image is removed. +You can remove an image using its short or long ID, its tag, or its digest. If +an image has one or more tag or digest reference, you must remove all of them +before the image is removed. $ sudo docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -1660,6 +1682,20 @@ removed before the image is removed. Untagged: test:latest Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 +An image pulled by digest has no tag associated with it: + + $ sudo docker images --digests + REPOSITORY TAG DIGEST IMAGE ID CREATED VIRTUAL SIZE + localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB + +To remove an image using its digest: + + $ sudo docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 + Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 + Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b + ## run Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md index 44d4c045..571c0a46 100644 --- a/docs/sources/reference/run.md +++ b/docs/sources/reference/run.md @@ -24,7 +24,7 @@ other `docker` command. The basic `docker run` command takes this form: - $ sudo docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...] + $ sudo docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] To learn how to interpret the types of `[OPTIONS]`, see [*Option types*](/reference/commandline/cli/#option-types). @@ -140,6 +140,12 @@ While not strictly a means of identifying a container, you can specify a version image you'd like to run the container with by adding `image[:tag]` to the command. For example, `docker run ubuntu:14.04`. +### Image[@digest] + +Images using the v2 or later image format have a content-addressable identifier +called a digest. As long as the input used to generate the image is unchanged, +the digest value is predictable and referenceable. + ## PID Settings (--pid) --pid="" : Set the PID (Process) Namespace mode for the container, 'host': use the host's PID namespace inside the container @@ -661,7 +667,7 @@ Dockerfile instruction and how the operator can override that setting. Recall the optional `COMMAND` in the Docker commandline: - $ sudo docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...] + $ sudo docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] This command is optional because the person who created the `IMAGE` may have already provided a default `COMMAND` using the Dockerfile `CMD`