From c7e0531c3ab1844423e64ef49619faa24471f2e3 Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Thu, 27 Aug 2015 21:02:59 -0700 Subject: [PATCH] Revise documentation for Docker LABEL, including review comments by @SvenDowideit and @thaJeztah in PR #15903. Signed-off-by: Charles Chan --- docs/userguide/labels-custom-metadata.md | 58 ++++++++++++------------ 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/userguide/labels-custom-metadata.md b/docs/userguide/labels-custom-metadata.md index 2be7f8597f..29f1594adf 100644 --- a/docs/userguide/labels-custom-metadata.md +++ b/docs/userguide/labels-custom-metadata.md @@ -11,34 +11,35 @@ parent = "mn_use_docker" # Apply custom metadata 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. +labels. Labels serve a wide range of uses, such as adding notes or licensing +information to an image, or to identify a host. 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. +*strings*. You can specify multiple labels but each `` must be +unique or the value will be overwritten. 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 >containers and images are new in Docker 1.6.0 ## Label keys (namespaces) -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: +Docker puts no hard restrictions on the `key` used for a label. However, using +simple keys can easily lead to conflicts. For example, you have chosen to +categorize your images by CPU architecture using "architecture" labels in +your Dockerfiles: LABEL architecture="amd64" LABEL architecture="ARMv7" -But a user can label images by building architectural style: +Another user may apply the same label based on a building's "architecture": LABEL architecture="Art Nouveau" -To prevent naming conflicts, Docker namespaces label keys using a reverse domain -notation. Use the following guidelines to name your keys: +To prevent naming conflicts, Docker recommends using namespaces to label keys +using 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 @@ -59,15 +60,14 @@ notation. Use the following guidelines to name your keys: cumbersome namespaces on the command-line. -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. +These are simply guidelines and Docker does not *enforce* them. However, for +the benefit of the community, you *should* use namespaces for your label keys. ## Store structured data in labels -Label values can contain any data type that can be stored as a string. For -example, consider this JSON: +Label values can contain any data type as long as it can be represented as a +string. For example, consider this JSON document: { @@ -87,31 +87,31 @@ You can store this struct in a label by serializing it to a string first: 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. +nested properties, the tool itself needs to implement this functionality. -## Add labels to images; the `LABEL` instruction +## Add labels to images -Adding labels to an image: +To add labels to an image, use the `LABEL` instruction in your Dockerfile: LABEL [.][=] ... -The `LABEL` instruction adds a label to your image, optionally setting its value. +The `LABEL` instruction adds a label to your image, optionally with a value. Use surrounding quotes or backslashes for labels that contain -white space character: +white space characters in the ``: LABEL vendor=ACME\ Incorporated LABEL com.example.version.is-beta LABEL com.example.version="0.0.1-beta" LABEL com.example.release-date="2015-02-12" -The `LABEL` instruction supports setting multiple labels in a single instruction -using this notation: +The `LABEL` instruction also supports setting multiple `` / `` pairs +in a single instruction: LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12" -Wrapping is allowed by using a backslash (`\`) as continuation marker: +Long lines can be split up by using a backslash (`\`) as continuation marker: LABEL vendor=ACME\ Incorporated \ com.example.is-beta \ @@ -120,7 +120,7 @@ Wrapping is allowed by using a backslash (`\`) as continuation marker: 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. +is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer. You can view the labels via the `docker inspect` command: @@ -147,16 +147,16 @@ You can view the labels via the `docker inspect` command: ## Query labels Besides storing metadata, you can filter images and containers by label. To list all -running containers that the `com.example.is-beta` label: +running containers that have 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" -List all running containers with a `color` label of `blue`: +List all running containers with the label `color` that have a value `blue`: $ docker ps --filter "label=color=blue" -List all images with `vendor` `ACME`: +List all images with the label `vendor` that have the value `ACME`: $ docker images --filter "label=vendor=ACME"