Restructure content about Docker object labels

A few points of work:

- Took the topic out of the left-hand nav and made it
  reachable from the User guide intro

- Condensed the topic's contents, presenting only conceptual
  info and pointing instead to the command-line references
  for each type of object

- Added brief information about the `LABELS` keyword to the
  Dockerfile reference

A big part of the point is to establish a pattern of
thinking and use around how Docker uses labels and what they
mean in different contexts.

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
(cherry picked from commit 5c4c062ffcdb8d7b8c104fd667571279c51d2ffd)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/userguide/eng-image/dockerfile_best-practices.md

@@ -134,6 +134,43 @@ image. We recommend the [Debian image](https://hub.docker.com/_/debian/)
 since it’s very tightly controlled and kept minimal (currently under 150 mb),
 while still being a full distribution.
 
+### LABEL
+
+[Understanding object labels](../labels-custom-metadata.md)
+
+You can add labels to your image to help organize images by project, record
+licensing information, to aid in automation, or for other reasons. For each
+label, add a line beginning with `LABEL` and with one or more key-value pairs.
+The following examples show the different acceptable formats. Explanatory comments
+are included inline.
+
+>**Note**: If your string contains spaces, it must be quoted **or** the spaces
+must be escaped. If your string contains inner quote characters (`"`), escape
+them as well.
+
+```dockerfile
+# Set one or more individual labels
+LABEL com.example.version="0.0.1-beta"
+LABEL vendor="ACME Incorporated"
+LABEL com.example.release-date="2015-02-12"
+LABEL com.example.version.is-production=""
+
+# Set multiple labels on one line
+LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
+
+# Set multiple labels at once, using line-continuation characters to break long lines
+LABEL vendor=ACME\ Incorporated \
+      com.example.is-beta= \
+      com.example.is-production="" \
+      com.example.version="0.0.1-beta" \
+      com.example.release-date="2015-02-12"
+```
+
+See [Understanding object labels](../labels-custom-metadata.md) for
+guidelines about acceptable label keys and values. For information about
+querying labels, refer to the items related to filtering in
+[Managing labels on objects](../labels-custom-metadata.md#managing-labels-on-objects).
+
 ### RUN
 
 [Dockerfile reference for the RUN instruction](../../reference/builder.md#run)
@@ -142,7 +179,7 @@ As always, to make your `Dockerfile` more readable, understandable, and
 maintainable, split long or complex `RUN` statements on multiple lines separated
 with backslashes.
 
-### apt-get
+#### apt-get
 
 Probably the most common use-case for `RUN` is an application of `apt-get`. The
 `RUN apt-get` command, because it installs packages, has several gotchas to look

docs/userguide/intro.md

@@ -3,6 +3,7 @@
 title = "Introduction"
 description = "Introduction to user guide"
 keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home,  intro"]
+identifier = "engine_guide_intro"
 [menu.main]
 parent="engine_guide"
 +++
@@ -64,6 +65,25 @@ learning how to manage data, volumes and mounts inside our containers.
 
 Go to [Managing Data in Containers](../tutorials/dockervolumes.md).
 
+## Managing metadata (labels) for Docker objects
+
+Labels are a mechanism for applying metadata to Docker objects, including:
+
+- Images
+- Containers
+- Local daemons
+- Volumes
+- Networks
+- Swarm nodes
+- Swarm services
+
+
+You can use labels to organize your images, record licensing information, annotate
+relationships between containers, volumes, and networks, or in any way that makes
+sense for your business or application.
+
+Go to [Managing Docker object labels](labels-custom-metadata.md).
+
 ## Docker products that complement Engine
 
 Often, one powerful technology spawns many other inventions that make that easier to get to, easier to use, and more powerful.  These spawned things share one common characteristic: they augment the central technology. The following Docker products expand on the core Docker Engine functions.

docs/userguide/labels-custom-metadata.md

@@ -1,230 +1,116 @@
 <!--[metadata]>
 +++
-title = "Apply custom metadata"
+title = "Managing Docker object labels"
-description = "Learn how to work with custom metadata in Docker, using labels."
+description = "Description of labels, which are used to manage metadata on Docker objects."
-keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples,  annotating"]
+keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples, annotating"]
 [menu.main]
-parent = "engine_guide"
+parent = "engine_guide_intro"
 weight=90
 +++
 <![end-metadata]-->
 
-# Apply custom metadata
+# About labels
 
-You can apply metadata to your images, containers, volumes, networks, nodes, services or daemons via
+Labels are a mechanism for applying metadata to Docker objects, including:
-labels. Labels serve a wide range of uses, such as adding notes or licensing
-information to an image, or to identify a host.
 
-A label is a `<key>` / `<value>` pair. Docker stores the label values as
+- Images
-*strings*. You can specify multiple labels but each `<key>` must be
+- Containers
-unique or the value will be overwritten. If you specify the same `key` several
+- Local daemons
-times but with different values, newer labels overwrite previous labels. Docker
+- Volumes
-uses the last `key=value` you supply.
+- Networks
+- Swarm nodes
+- Swarm services
 
->**Note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
+You can use labels to organize your images, record licensing information, annotate
->containers and images were added in Docker 1.6.0
+relationships between containers, volumes, and networks, or in any way that makes
+sense for your business or application.
 
-## Label keys (namespaces)
+# Label keys and values
 
-Docker puts no hard restrictions on the `key` used for a label. However, using
+A label is a key-value pair, stored as a string. You can specify multiple labels
-simple keys can easily lead to conflicts. For example, you have chosen to
+for an object, but each key-value pair must be unique within an object. If the
-categorize your images by CPU architecture using "architecture" labels in
+same key is given multiple values, the most-recently-written value overwrites
-your Dockerfiles:
+all previous values.
 
-    LABEL architecture="amd64"
+## Key format recommendations
 
-    LABEL architecture="ARMv7"
+A label _key_ is the left-hand side of the key-value pair. Keys are alphanumeric
+strings which may contain periods (`.`) and hyphens (`-`). Most Docker users use
+images created by other organizations, and the following guidelines help to
+prevent inadvertent duplication of labels across objects, especially if you plan
+to use labels as a mechanism for automation.
 
-Another user may apply the same label based on a building's "architecture":
+- Authors of third-party tools should prefix each label key with the
+  reverse DNS notation of a domain they own, such as `com.example.some-label`.
 
-    LABEL architecture="Art Nouveau"
+- Do not use a domain in your label key without the domain owner's permission.
-
-To prevent naming conflicts, Docker recommends using namespaces to label keys
-using reverse domain notation. Use the following guidelines to name your keys:
-
-- 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 `org.dockerproject.*` namespaces are
-  reserved for Docker's internal use.
+  reserved by Docker for internal use.
 
-- Keys should only consist of lower-cased alphanumeric characters,
+- Label keys should begin and end with a lower-case letter and should only
-  dots and dashes (for example, `[a-z0-9-.]`).
+  contain lower-case alphanumeric characters, the period character (`.`), and
+  the hyphen character (`-`). Consecutive periods or hyphens are not allowed.
 
-- Keys should start *and* end with an alpha numeric character.
+- The period character (`.`) separates namespace "fields". Label keys without
+  namespaces are reserved for CLI use, allowing users of the CLI to interactively
+  label Docker objects using shorter typing-friendly strings.
 
-- Keys may not contain consecutive dots or dashes.
+These guidelines are not currently enforced and additional guidelines may apply
+to specific use cases.
 
-- Keys *without* namespace (dots) are reserved for CLI use. This allows end-
+## Value guidelines
-  users to add metadata to their containers and images without having to type
+
-  cumbersome namespaces on the command-line.
+Label values can contain any data type that can be represented as a string,
+including (but not limited to) JSON, XML, CSV, or YAML. The only requirement is
+that the value be serialized to a string first, using a mechanism specific to
+the type of structure. For instance, to serialize JSON into a string, you might
+use the `JSON.stringify()` JavaScript method.
+
+Since Docker does not deserialize the value, you cannot treat a JSON or XML
+document as a nested structure when querying or filtering by label value unless
+you build this functionality into third-party tooling.
+
+# Managing labels on objects
+
+Each type of object with support for labels has mechanisms for adding and
+managing them and using them as they relate to that type of object. These links
+provide a good place to start learning about how you can use labels in your
+Docker deployments.
+
+Labels on images, containers, local daemons, volumes, and networks are static for
+the lifetime of the object. To change these labels you must recreate the object.
+Labels on swarm nodes and services can be updated dynamically.
 
 
-These are simply guidelines and Docker does not *enforce* them. However, for
+- Images and containers
-the benefit of the community, you *should* use namespaces for your label keys.
+  - [Adding labels to images](../reference/builder.md#label)
+  - [Overriding a container's labels at runtime](../reference/commandline/run.md#set-metadata-on-container-l-label-label-file)
+  - [Inspecting labels on images or containers](../reference/commandline/inspect.md)
+  - [Filtering images by label](../reference/commandline/inspect.md#filtering)
+  - [Filtering containers by label](../reference/commandline/ps.md#filtering)
 
+- Local Docker daemons
+  - [Adding labels to a Docker daemon at runtime](../reference/commandline/dockerd.md)
+  - [Inspecting a Docker daemon's labels](../reference/commandline/info.md)
 
-## Store structured data in labels
+- Volumes
+  - [Adding labels to volumes](../reference/commandline/volume_create.md)
+  - [Inspecting a volume's labels](../reference/commandline/volume_inspect.md)
+  - [Filtering volumes by label](../reference/commandline/volume_ls.md#filtering)
 
-Label values can contain any data type as long as it can be represented as a
+- Networks
-string. For example, consider this JSON document:
+  - [Adding labels to a network](../reference/commandline/network_create.md)
+  - [Inspecting a network's labels](../reference/commandline/network_inspect.md)
+  - [Filtering networks by label](../reference/commandline/network_ls.md#filtering)
 
+- Swarm nodes
+  - [Adding or updating a swarm node's labels](../reference/commandline/node_update.md#add-label-metadata-to-a-node)
+  - [Inspecting a swarm node's labels](../reference/commandline/node_inspect.md)
+  - [Filtering swarm nodes by label](../reference/commandline/node_ls.md#filtering)
 
-    {
+- Swarm services
-        "Description": "A containerized foobar",
+  - [Adding labels when creating a swarm service](../reference/commandline/service_create.md#set-metadata-on-a-service-l-label)
-        "Usage": "docker run --rm example/foobar [args]",
+  - [Updating a swarm service's labels](../reference/commandline/service_update.md)
-        "License": "GPL",
+  - [Inspecting a swarm service's labels](../reference/commandline/service_inspect.md)
-        "Version": "0.0.1-beta",
+  - [Filtering swarm services by label](../reference/commandline/service_ls.md#filtering)
-        "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 needs to implement this functionality.
-
-
-## Add labels to images
-
-To add labels to an image, use the `LABEL` instruction in your Dockerfile:
-
-
-    LABEL [<namespace>.]<key>=<value> ...
-
-The `LABEL` instruction adds a label to your image. A `LABEL` consists of a `<key>`
-and a `<value>`.
-Use an empty string for labels  that don't have a `<value>`,
-Use surrounding quotes or backslashes for labels that contain
-white space characters in the `<value>`:
-
-    LABEL vendor=ACME\ Incorporated
-    LABEL com.example.version.is-beta=
-    LABEL com.example.version.is-production=""
-    LABEL com.example.version="0.0.1-beta"
-    LABEL com.example.release-date="2015-02-12"
-
-The `LABEL` instruction also supports setting multiple `<key>` / `<value>` pairs
-in a single instruction:
-
-    LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
-
-Long lines can be split up by using a backslash (`\`) as continuation marker:
-
-    LABEL vendor=ACME\ Incorporated \
-          com.example.is-beta= \
-          com.example.is-production="" \
-          com.example.version="0.0.1-beta" \
-          com.example.release-date="2015-02-12"
-
-Docker recommends you add multiple labels in a single `LABEL` instruction. Using
-individual instructions for each label can result in an inefficient image. This
-is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer.
-
-You can view the labels via the `docker inspect` command:
-
-    $ docker inspect 4fa6e0f0c678
-
-    ...
-    "Labels": {
-        "vendor": "ACME Incorporated",
-        "com.example.is-beta": "",
-        "com.example.is-production": "",
-        "com.example.version": "0.0.1-beta",
-        "com.example.release-date": "2015-02-12"
-    }
-    ...
-
-    # Inspect labels on container
-    $ docker inspect -f "{{json .Config.Labels }}" 4fa6e0f0c678
-
-    {"Vendor":"ACME Incorporated","com.example.is-beta":"", "com.example.is-production":"", "com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}
-
-    # Inspect labels on images
-    $ docker inspect -f "{{json .ContainerConfig.Labels }}" myimage
-
-
-## Query labels
-
-Besides storing metadata, you can filter images and containers by label. To list all
-running containers that have the `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 the label `color` that have a value `blue`:
-
-    $ docker ps --filter "label=color=blue"
-
-List all images with the label `vendor` that have the value `ACME`:
-
-    $ docker images --filter "label=vendor=ACME"
-
-
-## Container labels
-
-    docker run \
-       -d \
-       --label com.example.group="webservers" \
-       --label com.example.environment="production" \
-       busybox \
-       top
-
-Please refer to the [Query labels](#query-labels) section above for information
-on how to query labels set on a container.
-
-
-## Daemon labels
-
-    dockerd \
-      --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
-     Running: 5
-     Paused: 2
-     Stopped: 5
-    Images: 672
-    Server Version: 1.9.0
-    Storage Driver: aufs
-     Root Dir: /var/lib/docker/aufs
-     Backing Filesystem: extfs
-     Dirs: 697
-     Dirperm1 Supported: true
-    Execution Driver: native-0.2
-    Logging Driver: json-file
-    Kernel Version: 3.19.0-22-generic
-    Operating System: Ubuntu 15.04
-    CPUs: 24
-    Total Memory: 62.86 GiB
-    Name: docker
-    ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S
-    Debug mode (server): true
-     File Descriptors: 59
-     Goroutines: 159
-     System Time: 2015-09-23T14:04:20.699842089+08:00
-     EventsListeners: 0
-     Init SHA1:
-     Init Path: /usr/bin/docker
-     Docker Root Dir: /var/lib/docker
-     Http Proxy: http://test:test@localhost:8080
-     Https Proxy: https://test:test@localhost:8080
-    WARNING: No swap limit support
-    Username: svendowideit
-    Registry: [https://index.docker.io/v1/]
-    Labels:
-     com.example.environment=production
-     com.example.storage=ssd