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> Upstream-commit: 7d89e66dac59999ae2f07970b273e227fdf73ea7 Component: engine
2015-02-17 01:36:03 +01:00
parent de26f9599e
commit f9d0cdbb89
13 changed files with 296 additions and 21 deletions
--- a/components/engine/docs/sources/userguide/labels-custom-metadata.md
+++ b/components/engine/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