labels-custom-metadata.md 6.4 KB

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