diff --git a/docs/man/Dockerfile.5.md b/docs/man/Dockerfile.5.md index d66bcad067..48e39ac3c3 100644 --- a/docs/man/Dockerfile.5.md +++ b/docs/man/Dockerfile.5.md @@ -143,6 +143,18 @@ A Dockerfile is similar to a Makefile. **CMD** executes nothing at build time, but specifies 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. + + 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. + + **EXPOSE** -- `EXPOSE [...]` The **EXPOSE** instruction informs Docker that the container listens on the diff --git a/docs/man/docker-create.1.md b/docs/man/docker-create.1.md index d5166ca93a..7fc7f98152 100644 --- a/docs/man/docker-create.1.md +++ b/docs/man/docker-create.1.md @@ -24,6 +24,8 @@ docker-create - Create a new container [**--help**] [**-i**|**--interactive**[=*false*]] [**--ipc**[=*IPC*]] +[**-l**|**--label**[=*[]*]] +[**--label-file**[=*[]*]] [**--link**[=*[]*]] [**--lxc-conf**[=*[]*]] [**-m**|**--memory**[=*MEMORY*]] @@ -102,6 +104,12 @@ IMAGE [COMMAND] [ARG...] 'container:': reuses another container shared memory, semaphores and message queues '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) + +**--label-file**=[] + Read in a line delimited file of labels + **--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 16fad991ce..253bb07ce2 100644 --- a/docs/man/docker-images.1.md +++ b/docs/man/docker-images.1.md @@ -34,7 +34,9 @@ versions. Show all images (by default filter out the intermediate image layers). The default is *false*. **-f**, **--filter**=[] - Provide filter values (i.e., 'dangling=true') + Provide filter values. Valid filters: + dangling=true - unlabeled images with no children + label= or label== **--help** Print usage statement diff --git a/docs/man/docker-inspect.1.md b/docs/man/docker-inspect.1.md index 23ec6bedef..85f6730004 100644 --- a/docs/man/docker-inspect.1.md +++ b/docs/man/docker-inspect.1.md @@ -83,6 +83,11 @@ To get information on a container use it's ID or instance name: "Ghost": false }, "Image": "df53773a4390e25936f9fd3739e0c0e60a62d024ea7b669282b27e65ae8458e6", + "Labels": { + "com.example.vendor": "Acme", + "com.example.license": "GPL", + "com.example.version": "1.0" + }, "NetworkSettings": { "IPAddress": "172.17.0.2", "IPPrefixLen": 16, diff --git a/docs/man/docker-ps.1.md b/docs/man/docker-ps.1.md index bd1e04d813..783f4621f6 100644 --- a/docs/man/docker-ps.1.md +++ b/docs/man/docker-ps.1.md @@ -36,6 +36,7 @@ the running containers. **-f**, **--filter**=[] Provide filter values. Valid filters: exited= - containers with exit code of + label= or label== status=(restarting|running|paused|exited) name= - container's name id= - container's ID diff --git a/docs/man/docker-run.1.md b/docs/man/docker-run.1.md index 587b9a2cd5..4b405920c2 100644 --- a/docs/man/docker-run.1.md +++ b/docs/man/docker-run.1.md @@ -25,6 +25,8 @@ docker-run - Run a command in a new container [**--help**] [**-i**|**--interactive**[=*false*]] [**--ipc**[=*IPC*]] +[**-l**|**--label**[=*[]*]] +[**--label-file**[=*[]*]] [**--link**[=*[]*]] [**--lxc-conf**[=*[]*]] [**-m**|**--memory**[=*MEMORY*]] @@ -197,6 +199,12 @@ ENTRYPOINT. 'container:': reuses another container shared memory, semaphores and message queues '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) + +**--label-file**=[] + Read in a line delimited file of labels + **--link**=[] Add link to another container in the form of :alias diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7e514d542f..51dd388677 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,6 +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/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 95a3535d0c..5e154b67e4 100644 --- a/docs/sources/reference/api/docker_remote_api.md +++ b/docs/sources/reference/api/docker_remote_api.md @@ -75,7 +75,7 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`. 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. -`LABEL "Vendor"="ACME Incorporated"` +`LABEL "com.example.vendor"="ACME Incorporated"` **New!** `POST /containers/(id)/attach` and `POST /exec/(id)/start` diff --git a/docs/sources/reference/api/docker_remote_api_v1.17.md b/docs/sources/reference/api/docker_remote_api_v1.17.md index 050e027465..d82faffe98 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.17.md +++ b/docs/sources/reference/api/docker_remote_api_v1.17.md @@ -130,9 +130,9 @@ Create a container "Entrypoint": "", "Image": "ubuntu", "Labels": { - "Vendor": "Acme", - "License": "GPL", - "Version": "1.0" + "com.example.vendor": "Acme", + "com.example.license": "GPL", + "com.example.version": "1.0" }, "Volumes": { "/tmp": {} @@ -194,7 +194,8 @@ 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 list of labels that will applied 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"]}` - **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 @@ -304,11 +305,11 @@ Return low-level information on the container `id` "ExposedPorts": null, "Hostname": "ba033ac44011", "Image": "ubuntu", - "Labels": { - "Vendor": "Acme", - "License": "GPL", - "Version": "1.0" - }, + "Labels": { + "com.example.vendor": "Acme", + "com.example.license": "GPL", + "com.example.version": "1.0" + }, "MacAddress": "", "Memory": 0, "MemorySwap": 0, @@ -1181,9 +1182,9 @@ Return low-level information on the image `name` "Dns": null, "Image": "ubuntu", "Labels": { - "Vendor": "Acme", - "License": "GPL", - "Version": "1.0" + "com.example.vendor": "Acme", + "com.example.license": "GPL", + "com.example.version": "1.0" }, "Volumes": null, "VolumesFrom": "", diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 00c70e6fa1..ff5821286d 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -331,13 +331,23 @@ default specified in `CMD`. ## LABEL LABEL = = = ... - --The `LABEL` instruction allows you to describe the image your `Dockerfile` -is building. `LABEL` is specified as name value pairs. This data can +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.label-without-value + LABEL com.example.label-with-value="foo" + LABEL version="1.0" + LABEL description="This my ACME image" vendor="ACME Products" - LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" - LABEL Version="1.0" +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." ## EXPOSE diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 08eb606c7b..79dbb6c8f5 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -791,6 +791,8 @@ 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) + --label-file=[] Read in a line delimited file of labels --link=[] Add link to another container --lxc-conf=[] Add custom lxc options -m, --memory="" Memory limit @@ -1143,6 +1145,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b Current filters: * dangling (boolean - true or false) + * label (`label=` or `label==`) ##### Untagged images @@ -1662,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 a container, for example com.example.key=value - -label-file=[] Read in a line delimited file of labels + -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 --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,6 +1840,36 @@ An example of a file passed with `--env-file` This will create and run a new container with the container name being `console`. + $ sudo docker run -l my-label --env 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 +`--env` 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. + +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; + + $ sudo docker run --env-file ./labels ubuntu bash + +The format of the labels-file is similar to that used for loading environment +variables (see `--env-file` above). An example of a file passed with `--env-file`; + + $ 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 +times. + +For additional information on working with labels, see +[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in +the user guide. + $ sudo docker run --link /redis:redis --name console ubuntu bash The `--link` flag will link the container named `/redis` into the newly diff --git a/docs/sources/userguide/labels-custom-metadata.md b/docs/sources/userguide/labels-custom-metadata.md new file mode 100644 index 0000000000..0824af4d62 --- /dev/null +++ b/docs/sources/userguide/labels-custom-metadata.md @@ -0,0 +1,194 @@ +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 + +## Labels - custom meta-data 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. + +Labels in Docker are implemented as `` / `` pairs and values are +stored as *strings*. + +>**note:** Support for daemon-labels was added in docker 1.4.1, labels on +>containers and images 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; + + LABEL architecture="amd64" + + LABEL architecture="ARMv7" + +But a user decided to label images by Architectural style + + LABEL architecture="Art Nouveau" + +To prevent such conflicts, Docker uses the convention to namespace label-names, +using a reverse domain notation; + + +- 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. +- 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 + 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. + + +### Storing structured data in labels + +Labels can store any type of data, as long as its stored as a string. + + + { + "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"] + } + +Which can be stored 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\"]}" + + +> **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. + + +### Adding labels to images; the `LABEL` instruction + +Adding labels to your + + + 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 + + + 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; + + 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; + + LABEL vendor=ACME\ Incorporated \ + com.example.is-beta \ + com.example.version="0.0.1-beta" \ + com.example.release-date="2015-02-12" + + +You can view the labels via `docker inspect` + + $ docker inspect 4fa6e0f0c678 + + ... + "Labels": { + "vendor": "ACME Incorporated", + "com.example.is-beta": "", + "com.example.version": "0.0.1-beta", + "com.example.release-date": "2015-02-12" + } + ... + + $ docker inspect -f "{{json .Labels }}" 4fa6e0f0c678 + + {"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; + + # 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"; + + $ docker ps --filter "label=color=blue" + +List all images with "vendor" "ACME" + + $ docker images --filter "label=vendor=ACME" + + +### Daemon labels + + + + docker -d \ + --dns 8.8.8.8 \ + --dns 8.8.4.4 \ + -H unix:///var/run/docker.sock \ + --label com.example.environment="production" \ + --label com.example.storage="ssd" + +And can be seen as part of the `docker info` output for the daemon; + + docker -D info + Containers: 12 + Images: 672 + Storage Driver: aufs + Root Dir: /var/lib/docker/aufs + Backing Filesystem: extfs + Dirs: 697 + Execution Driver: native-0.2 + Kernel Version: 3.13.0-32-generic + Operating System: Ubuntu 14.04.1 LTS + CPUs: 1 + Total Memory: 994.1 MiB + Name: docker.example.com + ID: RC3P:JTCT:32YS:XYSB:YUBG:VFED:AAJZ:W3YW:76XO:D7NN:TEVU:UCRW + Debug mode (server): false + Debug mode (client): true + Fds: 11 + Goroutines: 14 + EventsListeners: 0 + Init Path: /usr/bin/docker + Docker Root Dir: /var/lib/docker + WARNING: No swap limit support + Labels: + com.example.environment=production + com.example.storage=ssd diff --git a/runconfig/parse.go b/runconfig/parse.go index cc638efc1b..284a13a4a7 100644 --- a/runconfig/parse.go +++ b/runconfig/parse.go @@ -76,7 +76,7 @@ func Parse(cmd *flag.FlagSet, args []string) (*Config, *HostConfig, *flag.FlagSe cmd.Var(&flVolumes, []string{"v", "-volume"}, "Bind mount a volume") cmd.Var(&flLinks, []string{"#link", "-link"}, "Add link to another container") cmd.Var(&flDevices, []string{"-device"}, "Add a host device to the container") - cmd.Var(&flLabels, []string{"l", "-label"}, "Set meta data on a container, for example com.example.key=value") + cmd.Var(&flLabels, []string{"l", "-label"}, "Set meta data on a container") cmd.Var(&flLabelsFile, []string{"-label-file"}, "Read in a line delimited file of labels") cmd.Var(&flEnv, []string{"e", "-env"}, "Set environment variables") cmd.Var(&flEnvFile, []string{"-env-file"}, "Read in a file of environment variables")