From 6ddfe883dd0d6ce1f97a121652927ac1b1dbaefe Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Mon, 16 Mar 2015 21:49:33 -0700 Subject: [PATCH] Updating with Sven's comments and other tweaks Signed-off-by: Mary Anthony --- docs/man/Dockerfile.5.md | 38 ++++++---- docs/man/docker-commit.1.md | 2 +- docs/man/docker-create.1.md | 4 +- docs/man/docker-import.1.md | 2 +- docs/mkdocs.yml | 2 +- docs/sources/reference/builder.md | 9 +++ docs/sources/reference/commandline/cli.md | 31 ++++---- .../userguide/labels-custom-metadata.md | 76 +++++++++---------- 8 files changed, 87 insertions(+), 77 deletions(-) diff --git a/docs/man/Dockerfile.5.md b/docs/man/Dockerfile.5.md index d460c30c21..45bdbd0a28 100644 --- a/docs/man/Dockerfile.5.md +++ b/docs/man/Dockerfile.5.md @@ -159,8 +159,12 @@ A Dockerfile is similar to a Makefile. LABEL "com.example.vendor"="ACME Incorporated" ``` - An image can have more than one label. To specify multiple labels, separate each - key-value pair by a space. + An image can have more than one label. To specify multiple labels, separate + each key-value pair by a space. + + Labels are additive including `LABEL`s in `FROM` images. As the system + encounters and then applies a new label, new `key`s override any previous + labels with identical keys. To display an image's labels, use the `docker inspect` command. @@ -290,20 +294,22 @@ A Dockerfile is similar to a Makefile. **ONBUILD** -- `ONBUILD [INSTRUCTION]` - The **ONBUILD** instruction adds a trigger instruction to the image, which is - executed at a later time, when the image is used as the base for another - build. The trigger is executed in the context of the downstream build, as - if it had been inserted immediately after the **FROM** instruction in the - downstream Dockerfile. Any build instruction can be registered as a - trigger. This is useful if you are building an image to be - used as a base for building other images, for example an application build - environment or a daemon to be customized with a user-specific - configuration. For example, if your image is a reusable python - application builder, it requires application source code to be - added in a particular directory, and might require a build script - to be called after that. You can't just call **ADD** and **RUN** now, because - you don't yet have access to the application source code, and it - is different for each application build. + The **ONBUILD** instruction adds a trigger instruction to an image. The + trigger is executed at a later time, when the image is used as the base for + another build. Docker executes the trigger in the context of the downstream + build, as if the trigger existed immediately after the **FROM** instruction in + the downstream Dockerfile. + + You can register any build instruction as a trigger. A trigger is useful if + you are defining an image to use as a base for building other images. For + example, if you are defining an application build environment or a daemon that + is customized with a user-specific configuration. + + Consider an image intended as a reusable python application builder. It must + add application source code to a particular directory, and might need a build + script called after that. You can't just call **ADD** and **RUN** now, because + you don't yet have access to the application source code, and it is different + for each application build. -- Providing application developers with a boilerplate Dockerfile to copy-paste into their application is inefficient, error-prone, and diff --git a/docs/man/docker-commit.1.md b/docs/man/docker-commit.1.md index 663dfdc68f..e3459197a7 100644 --- a/docs/man/docker-commit.1.md +++ b/docs/man/docker-commit.1.md @@ -22,7 +22,7 @@ Using an existing container's name or ID you can create a new image. **-c** , **--change**=[] Apply specified Dockerfile instructions while committing the image - Supported Dockerfile instructions: CMD, ENTRYPOINT, ENV, EXPOSE, ONBUILD, USER, VOLUME, WORKDIR + Supported Dockerfile instructions: ADD|CMD|ENTRYPOINT|ENV|EXPOSE|FROM|MAINTAINER|RUN|USER|LABEL|VOLUME|WORKDIR|COPY **--help** Print usage statement diff --git a/docs/man/docker-create.1.md b/docs/man/docker-create.1.md index 91dcb8df30..4c462283f7 100644 --- a/docs/man/docker-create.1.md +++ b/docs/man/docker-create.1.md @@ -105,10 +105,10 @@ IMAGE [COMMAND] [ARG...] 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. **-l**, **--label**=[] - Set metadata on the container (e.g., --label=com.example.key=value) + Adds metadata to a container (e.g., --label=com.example.key=value) **--label-file**=[] - Read in a file of labels (EOL delimited) + Read labels from a file. Delimit each label with an EOL. **--link**=[] Add link to another container in the form of :alias diff --git a/docs/man/docker-import.1.md b/docs/man/docker-import.1.md index 3f9b8bb3e4..6b3899b6a7 100644 --- a/docs/man/docker-import.1.md +++ b/docs/man/docker-import.1.md @@ -13,7 +13,7 @@ URL|- [REPOSITORY[:TAG]] # OPTIONS **-c**, **--change**=[] Apply specified Dockerfile instructions while importing the image - Supported Dockerfile instructions: CMD, ENTRYPOINT, ENV, EXPOSE, ONBUILD, USER, VOLUME, WORKDIR + Supported Dockerfile instructions: `ADD`|`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`FROM`|`MAINTAINER`|`RUN`|`USER`|`LABEL`|`VOLUME`|`WORKDIR`|`COPY` # DESCRIPTION Create a new filesystem image from the contents of a tarball (`.tar`, diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 88447ad923..97e0bf197f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,7 +59,7 @@ pages: - ['userguide/dockerimages.md', 'User Guide', 'Working with Docker Images' ] - ['userguide/dockerlinks.md', 'User Guide', 'Linking containers together' ] - ['userguide/dockervolumes.md', 'User Guide', 'Managing data in containers' ] -- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom metadata in Docker' ] +- ['userguide/labels-custom-metadata.md', 'User Guide', 'Apply custom metadata' ] - ['userguide/dockerrepos.md', 'User Guide', 'Working with Docker Hub' ] - ['userguide/level1.md', '**HIDDEN**' ] - ['userguide/level2.md', '**HIDDEN**' ] diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 9a03c516ee..ecbfe376a6 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -347,6 +347,15 @@ key-value pair by an EOL. LABEL description="This text illustrates \ that label-values can span multiple lines." +Docker recommends combining labels in a single `LABEL` instruction where +possible. Each `LABEL` instruction produces a new layer which can result in an +inefficient image if you use many labels. This example results in four image +layers. + +Labels are additive including `LABEL`s in `FROM` images. As the system +encounters and then applies a new label, new `key`s override any previous labels +with identical keys. + To view an image's labels, use the `docker inspect` command. ## EXPOSE diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 4ce50a7bae..803a4c8d1d 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -749,8 +749,7 @@ If this behavior is undesired, set the 'p' option to false. The `--change` option will apply `Dockerfile` instructions to the image that is created. -Supported `Dockerfile` instructions: `CMD`, `ENTRYPOINT`, `ENV`, `EXPOSE`, -`ONBUILD`, `USER`, `VOLUME`, `WORKDIR` +Supported `Dockerfile` instructions: `ADD`|`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`FROM`|`MAINTAINER`|`RUN`|`USER`|`LABEL`|`VOLUME`|`WORKDIR`|`COPY` #### Commit a container @@ -1864,22 +1863,23 @@ A label is a a `key=value` pair that applies metadata to a container. To label a $ sudo docker run -l my-label --label com.example.foo=bar ubuntu bash -The `my-label` key doesn't specify so the label defaults to an empty -string(`""`). To add multiple labels, repeat the label flag (`-l` or -`--label`). +The `my-label` key doesn't specify a value so the label defaults to an empty +string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). -The `key=value` must be unique. If you specify the same key multiple times -with different values, each subsequent value overwrites the previous. Docker -applies the last `key=value` you supply. +The `key=value` must be unique to avoid overwriting the label value. If you +specify labels with identical keys but different values, each subsequent value +overwrites the previous. Docker uses the last `key=value` you supply. Use the `--label-file` flag to load multiple labels from a file. Delimit each label in the file with an EOL mark. The example below loads labels from a -labels file in the current directory; +labels file in the current directory: $ sudo docker run --label-file ./labels ubuntu bash -The label-file format is similar to the format for loading environment variables -(see `--env-file` above). The following example illustrates a label-file format; +The label-file format is similar to the format for loading environment +variables. (Unlike environment variables, labels are not visislbe to processes +running inside a container.) The following example illustrates a label-file +format: com.example.label1="a label" @@ -1887,12 +1887,11 @@ The label-file format is similar to the format for loading environment variables com.example.label2=another\ label com.example.label3 -You can load multiple label-files by supplying the `--label-file` flag multiple -times. +You can load multiple label-files by supplying multiple `--label-file` flags. -For additional information on working with labels, see -[*Labels - custom metadata in Docker*](/userguide/labels-custom-metadata/) in -the Docker User Guide. +For additional information on working with labels, see [*Labels - custom +metadata in Docker*](/userguide/labels-custom-metadata/) in the Docker User +Guide. $ sudo docker run --link /redis:redis --name console ubuntu bash diff --git a/docs/sources/userguide/labels-custom-metadata.md b/docs/sources/userguide/labels-custom-metadata.md index dc5c2407aa..7cf25c0609 100644 --- a/docs/sources/userguide/labels-custom-metadata.md +++ b/docs/sources/userguide/labels-custom-metadata.md @@ -1,26 +1,27 @@ -page_title: Labels - custom metadata in Docker +page_title: Apply custom metadata page_description: Learn how to work with custom metadata in Docker, using labels. page_keywords: Usage, user guide, labels, metadata, docker, documentation, examples, annotating -## Labels - custom metadata in Docker +# Apply custom metadata -You can add metadata to your images, containers, and daemons via -labels. Metadata can serve a wide range of uses. Use them to add notes or +You can apply metadata to your images, containers, or daemons via +labels. Metadata can serve a wide range of uses. Use labels to add notes or licensing information to an image or to identify a host. -A label is a `` / `` pair. Docker stores the values as *strings*. -You can specify multiple labels but each `` / `` must be unique. If -you specify the same `key` multiple times with different values, each subsequent -value overwrites the previous. Docker applies the last `key=value` you supply. +A label is a `` / `` pair. Docker stores the label values as +*strings*. You can specify multiple labels but each `` / `` must be +unique to avoid overwriting. If you specify the same `key` several times but with +different values, newer labels overwrite previous labels. Docker uses +the last `key=value` you supply. ->**note:** Support for daemon-labels was added in Docker 1.4.1. Labels on +>**Note:** Support for daemon-labels was added in Docker 1.4.1. Labels on >containers and images are new in Docker 1.6.0 -### Naming your labels - namespaces +## Label keys (namespaces) -Docker puts no hard restrictions on the label `key` you. However, labels can -conflict. For example, you can categorize your images by using a chip "architecture" -label: +Docker puts no hard restrictions on the label `key` you. However, labels with +simple keys can conflict. For example, you can categorize your images by using a +chip "architecture" label: LABEL architecture="amd64" @@ -30,9 +31,8 @@ But a user can label images by building architectural style: LABEL architecture="Art Nouveau" -To prevent such conflicts, Docker namespaces label keys using a reverse domain -notation. This notation has the following guidelines: - +To prevent naming conflicts, Docker namespaces label keys using a reverse domain +notation. Use the following guidelines to name your keys: - All (third-party) tools should prefix their keys with the reverse DNS notation of a domain controlled by the author. For @@ -49,19 +49,19 @@ notation. This notation has the following guidelines: - Keys may not contain consecutive dots or dashes. - Keys *without* namespace (dots) are reserved for CLI use. This allows end- - users to add metadata to their containers and images, without having to type + users to add metadata to their containers and images without having to type cumbersome namespaces on the command-line. -These are guidelines and are not enforced. Docker does not *enforce* them. -Failing following these guidelines can result in conflicting labels. If you're -building a tool that uses labels, you *should* use namespaces for your label keys. +These are guidelines and Docker does not *enforce* them. Failing following these +guidelines can result in conflicting labels. If you're building a tool that uses +labels, you *should* use namespaces for your label keys. -### Storing structured data in labels +## Store structured data in labels -Label values can contain any data type as long as the value can be stored as a -string. For example, consider this JSON: +Label values can contain any data type that can be stored as a string. For +example, consider this JSON: { @@ -78,15 +78,13 @@ You can store this struct in a label by serializing it to a string first: LABEL com.example.image-specs="{\"Description\":\"A containerized foobar\",\"Usage\":\"docker run --rm example\\/foobar [args]\",\"License\":\"GPL\",\"Version\":\"0.0.1-beta\",\"aBoolean\":true,\"aNumber\":0.01234,\"aNestedArray\":[\"a\",\"b\",\"c\"]}" -While it is *possible* to store structured data in label values, Docker treats this -data as a 'regular' string. This means that Docker doesn't offer ways to query -(filter) based on nested properties. - -If your tool needs to filter on nested properties, the tool itself should -implement this. +While it is *possible* to store structured data in label values, Docker treats +this data as a 'regular' string. This means that Docker doesn't offer ways to +query (filter) based on nested properties. If your tool needs to filter on +nested properties, the tool itself should implement this. -### Adding labels to images; the `LABEL` instruction +## Add labels to images; the `LABEL` instruction Adding labels to an image: @@ -103,7 +101,7 @@ white space character: LABEL com.example.release-date="2015-02-12" The `LABEL` instruction supports setting multiple labels in a single instruction -using this notation; +using this notation: LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12" @@ -114,10 +112,9 @@ Wrapping is allowed by using a backslash (`\`) as continuation marker: com.example.version="0.0.1-beta" \ com.example.release-date="2015-02-12" -Docker recommends combining labels in a single `LABEL` instruction instead of -using a `LABEL` instruction for each label. Each instruction in a Dockerfile -produces a new layer that can result in an inefficient image if you use many -labels. +Docker recommends you add multiple labels in a single `LABEL` instruction. Using +individual instructions for each label can result in an inefficient image. This +is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer. You can view the labels via the `docker inspect` command: @@ -137,11 +134,10 @@ You can view the labels via the `docker inspect` command: {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"} +## Query labels -### Querying labels - -Besides storing metadata, you can filter images and labels by label. To list all -running containers that have a `com.example.is-beta` label: +Besides storing metadata, you can filter images and containers by label. To list all +running containers that the `com.example.is-beta` label: # List all running containers that have a `com.example.is-beta` label $ docker ps --filter "label=com.example.is-beta" @@ -155,7 +151,7 @@ List all images with `vendor` `ACME`: $ docker images --filter "label=vendor=ACME" -### Daemon labels +## Daemon labels docker -d \