From 7d89e66dac59999ae2f07970b273e227fdf73ea7 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 17 Feb 2015 01:36:03 +0100 Subject: [PATCH] Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn Signed-off-by: Darren Shepherd --- docs/man/Dockerfile.5.md | 12 ++ docs/man/docker-create.1.md | 8 + docs/man/docker-images.1.md | 4 +- docs/man/docker-inspect.1.md | 5 + docs/man/docker-ps.1.md | 1 + docs/man/docker-run.1.md | 8 + docs/mkdocs.yml | 1 + .../reference/api/docker_remote_api.md | 2 +- .../reference/api/docker_remote_api_v1.17.md | 25 +-- docs/sources/reference/builder.md | 18 +- docs/sources/reference/commandline/cli.md | 37 +++- .../userguide/labels-custom-metadata.md | 194 ++++++++++++++++++ runconfig/parse.go | 2 +- 13 files changed, 296 insertions(+), 21 deletions(-) create mode 100644 docs/sources/userguide/labels-custom-metadata.md 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")