Merge pull request #9882 from ibuildthecloud/labels

Proposal: One Meta Data to Rule Them All => Labels

docs/man/Dockerfile.5.md

@@ -149,6 +149,21 @@ 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 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 a space.
+
+  To display an image's labels, use the `docker inspect` command.
+
 **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 metadata on the container (e.g., --label=com.example.key=value)
+
+**--label-file**=[]
+   Read in a file of labels (EOL delimited)
+
 **--link**=[]
    Add link to another container in the form of <name or id>:alias
 

docs/man/docker-images.1.md

@@ -34,7 +34,7 @@ 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')
+   Filters the output. The dangling=true filter finds unused images. While label=com.foo=amd64 filters for images with a com.foo value of amd64. The label=com.foo filter finds images with the label com.foo of any 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 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 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 metadata 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

@@ -71,15 +71,32 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
 
 ### What's new
 
+The build supports `LABEL` command. Use this to add metadata
+to an image. For example you could add data describing the content of an image.
+
+`LABEL "com.example.vendor"="ACME Incorporated"`
+
+**New!**
 `POST /containers/(id)/attach` and `POST /exec/(id)/start`
 
 **New!**
 Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers.
 
+`POST /containers/create`
+
+**New!**
+You can set labels on container create describing the container.
+
+`GET /containers/json`
+
+**New!**
+The endpoint returns the labels associated with the containers (`Labels`).
+
 `GET /containers/(id)/json`
 
 **New!**
 This endpoint now returns the list current execs associated with the container (`ExecIDs`).
+This endpoint now returns the container labels (`Config.Labels`).
 
 `POST /containers/(id)/rename`
 
@@ -98,6 +115,12 @@ root filesystem as read only.
 **New!**
 This endpoint returns a live stream of a container's resource usage statistics.
 
+`GET /images/json`
+
+**New!**
+This endpoint now returns the labels associated with each image (`Labels`).
+
+
 ## v1.16
 
 ### Full Documentation

docs/sources/reference/api/docker_remote_api_v1.18.md

@@ -125,6 +125,11 @@ Create a container
              ],
              "Entrypoint": "",
              "Image": "ubuntu",
+             "Labels": {
+                     "com.example.vendor": "Acme",
+                     "com.example.license": "GPL",
+                     "com.example.version": "1.0"
+             },
              "Volumes": {
                      "/tmp": {}
              },
@@ -191,6 +196,7 @@ 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** - Adds a map of labels that to a container. To specify a map: `{"key":"value"[,"key2":"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
@@ -301,6 +307,11 @@ Return low-level information on the container `id`
 			"ExposedPorts": null,
 			"Hostname": "ba033ac44011",
 			"Image": "ubuntu",
+			"Labels": {
+				"com.example.vendor": "Acme",
+				"com.example.license": "GPL",
+				"com.example.version": "1.0"
+			},
 			"MacAddress": "",
 			"NetworkDisabled": false,
 			"OnBuild": null,
@@ -1185,6 +1196,11 @@ Return low-level information on the image `name`
                              "Cmd": ["/bin/bash"],
                              "Dns": null,
                              "Image": "ubuntu",
+                             "Labels": {
+                                 "com.example.vendor": "Acme",
+                                 "com.example.license": "GPL",
+                                 "com.example.version": "1.0"
+                             },
                              "Volumes": null,
                              "VolumesFrom": "",
                              "WorkingDir": ""

docs/sources/reference/builder.md

@@ -328,6 +328,27 @@ default specified in `CMD`.
 > the result; `CMD` does not execute anything at build time, but specifies
 > the intended command for the image.
 
+## LABEL
+
+    LABEL <key>=<value> <key>=<value> <key>=<value> ...
+
+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 text illustrates \
+    that label-values can span multiple lines."
+
+To view an image's labels, use the `docker inspect` command.
+
 ## EXPOSE
 
     EXPOSE <port> [<port>...]
@@ -907,6 +928,7 @@ For example you might add something like this:
     FROM      ubuntu
     MAINTAINER Victor Vieux <victor@docker.com>
 
+    LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products" Version="1.0"
     RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server
 
     # Firefox over VNC

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 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
       -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=<key>` or `label=<key>=<value>`)
 
 ##### Untagged images
 
@@ -1685,6 +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 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
@@ -1855,8 +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
+
+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`).
+
+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 label-file format is similar to the format for loading environment variables
+(see `--env-file` above). The following example illustrates a label-file format;
+
+    com.example.label1="a label"
+
+    # this is a comment
+    com.example.label2=another\ label
+    com.example.label3
+
+You can load multiple label-files by supplying the `--label-file` flag multiple
+times.
+
+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
 

docs/sources/userguide/labels-custom-metadata.md

@@ -0,0 +1,194 @@
+page_title: Labels - custom metadata in Docker
+page_description: Learn how to work with custom metadata in Docker, using labels.
+page_keywords: Usage, user guide, labels, metadata, docker, documentation, examples, annotating
+
+## Labels - custom metadata in Docker
+
+You can add metadata to your images, containers, and daemons via
+labels. Metadata can serve a wide range of uses. Use them to add notes or
+licensing information to an image or to identify a host.
+
+A label is a `<key>` / `<value>` pair. Docker stores the values as *strings*.
+You can specify multiple labels but each `<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.
+
+>**note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
+>containers and images are new in Docker 1.6.0
+
+### Naming your labels - namespaces
+
+Docker puts no hard restrictions on the label `key` you. However, labels can
+conflict. For example, you can categorize your images by using a chip "architecture"
+label:
+
+    LABEL architecture="amd64"
+
+    LABEL architecture="ARMv7"
+
+But a user can label images by building architectural style:
+
+    LABEL architecture="Art Nouveau"
+
+To prevent such conflicts, Docker namespaces label keys using a reverse domain
+notation. This notation has the following guidelines:
+
+
+- All (third-party) tools should prefix their keys with the
+  reverse DNS notation of a domain controlled by the author. For
+  example, `com.example.some-label`.
+
+- The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are
+  reserved for Docker's internal use.
+
+- Keys should only consist of lower-cased alphanumeric characters,
+  dots and dashes (for example, `[a-z0-9-.]`)
+
+- Keys should start *and* end with an alpha numeric character
+
+- Keys may not contain consecutive dots or dashes.
+
+- Keys *without* namespace (dots) are reserved for CLI use. This allows end-
+  users to add metadata to their containers and images, without having to type
+  cumbersome namespaces on the command-line.
+
+
+These are guidelines and are not enforced. Docker does not *enforce* them.
+Failing following these guidelines can result in conflicting labels. If you're
+building a tool that uses labels, you *should* use namespaces for your label keys.
+
+
+### Storing structured data in labels
+
+Label values can contain any data type as long as the value can be stored as a
+string. For example, consider this JSON:
+
+
+    {
+        "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"]
+    }
+
+You can store this struct 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\"]}"
+
+While it is *possible* to store structured data in label values, Docker treats this
+data as 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 an image:
+
+
+    LABEL [<namespace>.]<key>[=<value>] ...
+
+The `LABEL` instruction adds a label to your image, optionally setting its value.
+Use surrounding quotes or backslashes for labels that contain
+white space character:
+
+    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"
+
+Docker recommends combining labels in a single `LABEL` instruction instead of
+using a `LABEL` instruction for each label. Each instruction in a Dockerfile
+produces a new layer that can result in an inefficient image if you use many
+labels.
+
+You can view the labels via the `docker inspect` command:
+
+    $ 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"}
+
+
+
+### Querying labels
+
+Besides storing metadata, you can filter images and labels by label. To 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 of `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"
+
+These labels appear 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