1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
moby--moby/docs/userguide/labels-custom-metadata.md

202 lines
6.6 KiB
Markdown
Raw Normal View History

<!--[metadata]>
+++
title = "Apply custom metadata"
description = "Learn how to work with custom metadata in Docker, using labels."
keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples, annotating"]
[menu.main]
parent = "mn_use_docker"
+++
<![end-metadata]-->
# Apply custom metadata
You can apply metadata to your images, containers, or daemons via
labels. Metadata can serve a wide range of uses. Use labels to add 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
*strings*. You can specify multiple labels but each `<key>` / `<value>` must be
unique to avoid overwriting. If you specify the same `key` several times but with
different values, newer labels overwrite previous labels. Docker uses
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
## Label keys (namespaces)
Docker puts no hard restrictions on the label `key` you. However, labels with
simple keys 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 naming conflicts, Docker namespaces label keys using a 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.
- 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 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.
## Store structured data in labels
Label values can contain any data type that 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.
## Add 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 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.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.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 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 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 daemon \
--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
Logging Driver: json-file
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
File Descriptors: 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