From b5c9f3f13a66c0651e54db2feaf86b627bf88dce 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/sources/reference/builder.md | 18 ++++++++--- docs/sources/reference/commandline/cli.md | 37 +++++++++++++++++++++-- 2 files changed, 49 insertions(+), 6 deletions(-) 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 64a5f9a82c..2ba42004cf 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -814,6 +814,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 @@ -1166,6 +1168,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 @@ -1685,8 +1688,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 @@ -1860,6 +1863,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