diff --git a/docs/man/Dockerfile.5.md b/docs/man/Dockerfile.5.md index 48e39ac3c3..2f2b93686e 100644 --- a/docs/man/Dockerfile.5.md +++ b/docs/man/Dockerfile.5.md @@ -144,16 +144,19 @@ A Dockerfile is similar to a Makefile. the image. **LABEL** - --**LABEL [=] [[=] ...]** + -- `LABEL [=] [[=] ...]` + The **LABEL** instruction adds metadata to an image. A **LABEL** is a + key-value pair. To include spaces within a **LABEL** value, use quotes and + blackslashes as you would in command-line parsing. - The **LABEL** instruction allows you to add meta-data to the image your - Dockerfile is building. LABEL is specified as name value pairs. This data can - be retrieved using the `docker inspect` command. + ``` + LABEL "com.example.vendor"="ACME Incorporated" + ``` - The LABEL instruction allows for multiple labels to be set at one time. Like - command line parsing, quotes and backslashes can be used to include spaces - within values. + An image can have more than one label. To specify multiple labels, separate each + key-value pair by a space. + To display an image's labels, use the `docker inspect` command. **EXPOSE** -- `EXPOSE [...]` diff --git a/docs/man/docker-create.1.md b/docs/man/docker-create.1.md index 7fc7f98152..310b6d0ddc 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 meta data on the container (e.g., --label=com.example.key=value) + Set metadata on the container (e.g., --label=com.example.key=value) **--label-file**=[] - Read in a line delimited file of labels + Read in a file of labels (EOL delimited) **--link**=[] Add link to another container in the form of :alias diff --git a/docs/man/docker-images.1.md b/docs/man/docker-images.1.md index 253bb07ce2..c82d2883f7 100644 --- a/docs/man/docker-images.1.md +++ b/docs/man/docker-images.1.md @@ -34,9 +34,7 @@ versions. Show all images (by default filter out the intermediate image layers). The default is *false*. **-f**, **--filter**=[] - Provide filter values. Valid filters: - dangling=true - unlabeled images with no children - label= or label== + Filters the output. The dangling=true filter finds unused images. While label=com.foo=amd64 filters for images with a com.foo value of amd64. The label=com.foo filter finds images with the label com.foo of any value. **--help** Print usage statement diff --git a/docs/man/docker-run.1.md b/docs/man/docker-run.1.md index 4b405920c2..3402dc6ae7 100644 --- a/docs/man/docker-run.1.md +++ b/docs/man/docker-run.1.md @@ -200,7 +200,7 @@ ENTRYPOINT. '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 meta data on the container (e.g., --label=com.example.key=value) + Set metadata on the container (e.g., --label com.example.key=value) **--label-file**=[] Read in a line delimited file of labels diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 51dd388677..814f434394 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 meta-data in Docker' ] +- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom metadata in Docker' ] - ['userguide/dockerrepos.md', 'User Guide', 'Working with Docker Hub' ] - ['userguide/level1.md', '**HIDDEN**' ] - ['userguide/level2.md', '**HIDDEN**' ] diff --git a/docs/sources/reference/api/docker_remote_api.md b/docs/sources/reference/api/docker_remote_api.md index 5e154b67e4..10c8c62aaa 100644 --- a/docs/sources/reference/api/docker_remote_api.md +++ b/docs/sources/reference/api/docker_remote_api.md @@ -71,9 +71,8 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`. ### What's new -**New!** -Build now has support for `LABEL` command which can be used to add user data -to an image. For example you could add data describing the content of an image. +The build supports `LABEL` command. Use this to add metadata +to an image. For example you could add data describing the content of an image. `LABEL "com.example.vendor"="ACME Incorporated"` @@ -91,7 +90,7 @@ You can set labels on container create describing the container. `GET /containers/json` **New!** -This endpoint now returns the labels associated with each container (`Labels`). +The endpoint returns the labels associated with the containers (`Labels`). `GET /containers/(id)/json` diff --git a/docs/sources/reference/api/docker_remote_api_v1.18.md b/docs/sources/reference/api/docker_remote_api_v1.18.md index fe6b59298d..c7e1607aeb 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.18.md +++ b/docs/sources/reference/api/docker_remote_api_v1.18.md @@ -195,8 +195,7 @@ Json Parameters: - **OpenStdin** - Boolean value, opens stdin, - **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects. - **Env** - A list of environment variables in the form of `VAR=value` -- **Labels** - A map of labels and their values that will be added to the - container. It should be specified in the form `{"name":"value"[,"name2":"value2"]}` +- **Labels** - Adds a map of labels that to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}` - **Cmd** - Command to run specified as a string or an array of strings. - **Entrypoint** - Set the entrypoint for the container a a string or an array of strings diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index ff5821286d..9a03c516ee 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -329,26 +329,26 @@ default specified in `CMD`. > the intended command for the image. ## LABEL - LABEL = = = ... -The `LABEL` instruction allows you to add meta-data to the image your -`Dockerfile` is building. `LABEL` is specified as name value pairs. This data can -be retrieved using the `docker inspect` command + LABEL = = = ... + +The `LABEL` instruction adds metadata to an image. A `LABEL` is a +key-value pair. To include spaces within a `LABEL` value, use quotes and +blackslashes as you would in command-line parsing. + + LABEL "com.example.vendor"="ACME Incorporated" + +An image can have more than one label. To specify multiple labels, separate each +key-value pair by an EOL. LABEL com.example.label-without-value LABEL com.example.label-with-value="foo" LABEL version="1.0" - LABEL description="This my ACME image" vendor="ACME Products" - -As illustrated above, the `LABEL` instruction allows for multiple labels to be -set at one time. Like command line parsing, quotes and backslashes can be used -to include spaces within values. - -For example: - LABEL description="This text illustrates \ that label-values can span multiple lines." +To view an image's labels, use the `docker inspect` command. + ## EXPOSE EXPOSE [...] diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 284aefa12b..b8e579840d 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -791,7 +791,7 @@ Creates a new container. -h, --hostname="" Container host name -i, --interactive=false Keep STDIN open even if not attached --ipc="" IPC namespace to use - -l, --label=[] Set meta data on the container (e.g., --label=com.example.key=value) + -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) --label-file=[] Read in a line delimited file of labels --link=[] Add link to another container --lxc-conf=[] Add custom lxc options @@ -1665,8 +1665,8 @@ removed before the image is removed. --link=[] Add link to another container --lxc-conf=[] Add custom lxc options -m, --memory="" Memory limit - -l, --label=[] Set meta data on the container (e.g., --label=com.example.key=value) - --label-file=[] Read in a line delimited file of labels + -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) + --label-file=[] Read in a file of labels (EOL delimited) --mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33) --memory-swap="" Total memory (memory + swap), '-1' to disable swap --name="" Assign a name to the container @@ -1837,38 +1837,39 @@ An example of a file passed with `--env-file` $ sudo docker run --name console -t -i ubuntu bash -This will create and run a new container with the container name being -`console`. +A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels: $ sudo docker run -l my-label --label com.example.foo=bar ubuntu bash -This sets two labels on the container. Label "my-label" doesn't have a value -specified and will default to "" (empty string) for its value. Both `-l` and -`--label` can be repeated to add more labels. Label names are unique; if the same -label is specified multiple times, latter values overwrite the previous value. +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`). -Labels can also be loaded from a line delimited file of labels using the -`--label-file` flag. The example below will load labels from a file named `labels` -in the current directory; +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. + +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; $ sudo docker run --label-file ./labels ubuntu bash -The format of the labels-file is similar to that used for loading environment -variables (see `--label-file` above). An example of a file passed with `--label-file`; +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; - $ cat ./labels com.example.label1="a label" # this is a comment com.example.label2=another\ label com.example.label3 -Multiple label-files can be loaded by providing the `--label-file` multiple +You can load multiple label-files by supplying the `--label-file` flag multiple times. -For additional information on working with labels, see -[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in -the 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 0824af4d62..dc5c2407aa 100644 --- a/docs/sources/userguide/labels-custom-metadata.md +++ b/docs/sources/userguide/labels-custom-metadata.md @@ -1,61 +1,67 @@ -page_title: Labels - custom meta-data in Docker -page_description: Learn how to work with custom meta-data in Docker, using labels. -page_keywords: Usage, user guide, labels, meta-data, docker, documentation, examples, annotating +page_title: Labels - custom metadata in Docker +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 meta-data in Docker +## Labels - custom metadata in Docker -Docker enables you to add meta-data to your images, containers, and daemons via -labels. Meta-data can serve a wide range of uses ranging from adding notes or -licensing information to an image to identifying a host. +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 +licensing information to an image or to identify a host. -Labels in Docker are implemented as `` / `` pairs and values are -stored as *strings*. +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. ->**note:** Support for daemon-labels was added in docker 1.4.1, labels on ->containers and images in docker 1.6.0 +>**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 -Docker puts no hard restrictions on the names you pick for your labels, however, -it's easy for labels to "conflict". - -For example, you're building a tool that categorizes your images in -architectures, doing so by using an "architecture" label; +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: LABEL architecture="amd64" LABEL architecture="ARMv7" -But a user decided to label images by Architectural style +But a user can label images by building architectural style: LABEL architecture="Art Nouveau" -To prevent such conflicts, Docker uses the convention to namespace label-names, -using a reverse domain notation; +To prevent such conflicts, Docker namespaces label keys using a reverse domain +notation. This notation has the following guidelines: -- All (third-party) tools should namespace (prefix) their labels with the - reverse DNS notation of a domain controlled by the author of the tool. For - example, "com.example.some-label". -- Namespaced labels should only consist of lower-cased alphanumeric characters, - dots and dashes (in short, `[a-z0-9-.]`), should start *and* end with an alpha - numeric character, and may not contain consecutive dots or dashes. +- All (third-party) tools should prefix their keys with the + reverse DNS notation of a domain controlled by the author. For + example, `com.example.some-label`. + - The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are reserved for Docker's internal use. -- Labels *without* namespace (dots) are reserved for CLI use. This allows end- - users to add meta-data to their containers and images, without having to type + +- Keys should only consist of lower-cased alphanumeric characters, + dots and dashes (for example, `[a-z0-9-.]`) + +- Keys should start *and* end with an alpha numeric character + +- 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 cumbersome namespaces on the command-line. -> **Note:** Even though Docker does not *enforce* you to use namespaces, -> preventing to do so will likely result in conflicting usage of labels. -> If you're building a tool that uses labels, you *should* use namespaces -> for your labels. +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. ### Storing structured data in labels -Labels can store any type of data, as long as its stored as a string. +Label values can contain any data type as long as the value can be stored as a +string. For example, consider this JSON: { @@ -68,31 +74,28 @@ Labels can store any type of data, as long as its stored as a string. "aNestedArray": ["a", "b", "c"] } -Which can be stored in a label by serializing it to a string first; +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. -> **Note:** Although the example above shows it's *possible* to store structured -> data in labels, Docker does not treat this data any other way than 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. +If your tool needs to filter on nested properties, the tool itself should +implement this. ### Adding labels to images; the `LABEL` instruction -Adding labels to your +Adding labels to an image: - LABEL [.][=] ... + LABEL [.][=] ... The `LABEL` instruction adds a label to your image, optionally setting its value. -Quotes surrounding name and value are optional, but required if they contain -white space characters. Alternatively, backslashes can be used. - -Label values only support strings - +Use surrounding quotes or backslashes for labels that contain +white space character: LABEL vendor=ACME\ Incorporated LABEL com.example.version.is-beta @@ -104,15 +107,19 @@ using this notation; 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; +Wrapping is allowed by using a backslash (`\`) as continuation marker: LABEL vendor=ACME\ Incorporated \ com.example.is-beta \ 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. -You can view the labels via `docker inspect` +You can view the labels via the `docker inspect` command: $ docker inspect 4fa6e0f0c678 @@ -129,27 +136,21 @@ You can view the labels via `docker inspect` {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"} -> **note:** We recommend combining labels in a single `LABEl` instruction in -> stead of using a `LABEL` instruction for each label. Each instruction in a -> Dockerfile produces a new layer, which can result in an inefficient image if -> many labels are used. + ### Querying labels -Besides storing meta-data, labels can be used to filter your images and -containers. - -List all running containers that have a `com.example.is-beta` label; +Besides storing metadata, you can filter images and labels by label. To list all +running containers that have a `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 set to "blue"; +List all running containers with a `color` label of `blue`: $ docker ps --filter "label=color=blue" -List all images with "vendor" "ACME" +List all images with `vendor` `ACME`: $ docker images --filter "label=vendor=ACME" @@ -157,7 +158,6 @@ List all images with "vendor" "ACME" ### Daemon labels - docker -d \ --dns 8.8.8.8 \ --dns 8.8.4.4 \ @@ -165,7 +165,7 @@ List all images with "vendor" "ACME" --label com.example.environment="production" \ --label com.example.storage="ssd" -And can be seen as part of the `docker info` output for the daemon; +These labels appear as part of the `docker info` output for the daemon: docker -D info Containers: 12