From bfca1f4258346e1990b090342b5b1898ad8f41a8 Mon Sep 17 00:00:00 2001 From: Darren Shepherd Date: Mon, 16 Mar 2015 13:28:55 -0700 Subject: [PATCH] Documentation changes for labels Signed-off-by: Darren Shepherd --- docs/sources/reference/builder.md | 24 +++++++------- docs/sources/reference/commandline/cli.md | 39 ++++++++++++----------- 2 files changed, 32 insertions(+), 31 deletions(-) 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 f69ff67fd7..4ce50a7bae 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -814,7 +814,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 @@ -1688,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 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 @@ -1860,38 +1860,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