5.11 Using Labels to Define Metadata

You can use labels to add metadata to the Docker daemon and to Docker containers and images. In the Dockerfile, a LABEL instruction defines an image label that can contain one or more key-value pairs, for example:

LABEL com.mydom.dept="ITGROUP" \
      com.mydom.version="1.0.0-ga" \
      com.mydom.is-final \
      com.mydom.released="June 6, 2015"

In this example, each key name is prefixed by the domain name in reverse DNS form (com.mydom.) to guard against name-space conflicts. Key values are always expressed as strings and are not interpreted by Docker. If you omit the value, you can use the presence or absence of the key in the metadata to encode information such as the release status. The backslash characters allow you to extend the label definition across several lines.

You can use the docker inspect command to display the labels that are associated with an image, for example:

$ docker inspect 7ac15076dcc1
"Labels": {
    "com.mydom.dept": "ITGROUP",
    "com.mydom.version": "1.0.0-ga",
    "com.mydom.is-final": "",
    "com.mydom.release-date": "June 6, 2015"

You can use the --filter "label=key[=value]" option with the docker images and docker ps commands to list the images and running containers on which a metadata value has been set, for example:

$ docker images --filter "label=com.mydom.dept='DEVGROUP'"
$ docker ps --filter "label=com.mydom.is-beta2"
$ docker ps --filter "label=env=Oracle\ Linux\ 7"

For containers, you can use --label key=[value] options with the docker create and docker run commands to define key-value pairs, for example:

$ docker run -i -t --rm testapp:1.0 --label run="11" --label platform="Oracle Linux 7"

For the Docker Engine, you can use --label key=[value] options if you start docker from the command line or edit the docker configuration file /etc/sysconfig/docker.

OPTIONS=" --label com.mydom.dept='DEVGROUP'"

Alternately, you can append these options to a list in the /etc/docker/daemon.json file, for example:

  "labels": ["com.mydom.dept='DEVGROUP'", "com.mydom.version='1.0.0-ga'"]

After adding or modifying a configuration file while the docker service is running, run the command systemctl daemon-reload to tell systemd to reload the configuration for the service.

As containers and the Docker daemon are transitory and run in a known environment, it is not usually necessary to apply reverse domain name prefixes to key names.