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 <github@gone.nl>
Signed-off-by: Darren Shepherd <darren@rancher.com>

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 <key>[=<value>] [<key>[=<value>] ...]**
+
+ 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 <port> [<port>...]`
   The **EXPOSE** instruction informs Docker that the container listens on the

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:<name|id>': 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 <name or id>:alias
 

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=<key> or label=<key>=<value>
 
 **--help**
   Print usage statement

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,

docs/man/docker-ps.1.md

@@ -36,6 +36,7 @@ the running containers.
 **-f**, **--filter**=[]
    Provide filter values. Valid filters:
                           exited=<int> - containers with exit code of <int>
+                          label=<key> or label=<key>=<value>
                           status=(restarting|running|paused|exited)
                           name=<string> - container's name
                           id=<ID> - container's ID

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:<name|id>': 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 <name or id>:alias
 

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**' ]

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`

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": "",

docs/sources/reference/builder.md

@@ -331,13 +331,23 @@ default specified in `CMD`.
 ## LABEL
    LABEL <key>=<value> <key>=<value> <key>=<value> ...
 
- --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
 

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=<key>` or `label=<key>=<value>`)
 
 ##### 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

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 `<key>` / `<value>` 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 [<namespace>.]<name>[=<value>] ...
+
+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

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")