Difficulty: Beginner
Estimated Time: 10 minutes

When running containers in production, it can be useful to add additional metadata relating to the container to help their management. This metadata could be related to which version of the code is running, which applications or users own the container or define special criteria such as which servers they should run on.

This additional data is managed via Docker Labels. Labels allow you to define custom metadata about a container or image which can later be inspected or used as part of a filter.

This scenario guides you though creating and querying the metadata for containers and images.

There are recommended guidelines to follow when working with labels to ensure they're consistent and manageable as defined by Docker.

Firstly, all tools should prefix their keys with the reverse DNS notation of a domain controlled by the author. For example, com.katacoda.some-label.

Secondly, if you're creating labels for CLI use, then they should follow the DNS notation making it easier for users to type.

Finally, keys should only consist of lower-cased alphanumeric characters, dots and dashes (for example, [a-z0-9-.])

In this scenario we explored how you can use labels to assign metadata to your Docker containers and images. This metadata can provide additional context around individual items or as use with a filter to find the information you're looking for.

As mentioned at the beginning, there are a number of recommended guidelines to follow when working with labels to ensure they're consistent and manageable as defined by Docker.

Firstly, all tools should prefix their keys with the reverse DNS notation of a domain controlled by the author. For example, com.joinscrapbook.some-label.

Secondly, if you're creating the labels for CLI use then it they should not follow the DNS notation making it easier for users to type.

Finally, keys should only consist of lower-cased alphanumeric characters, dots and dashes (for example, [a-z0-9-.])

Don’t stop now! The next scenario will only take about 10 minutes to complete.

Docker Metadata & Labels

Step 1 of 5

Step 1 - Docker Containers

Labels can be attached to containers when they are launched via docker run. A container can have multiple labels attached to them at any one time.

Notice in this example, because we're using the labels are for use with the CLI, and not an automated tool, we're not using the DNS notation format.

Single Label

To add a single label you use the l =<value> option. The example below assigns a label called user with an ID to the container. This would allow us to query for all the containers running related to that particular user.

docker run -l user=12345 -d redis

External File

If you're adding multiple labels, then these can come from an external file. The file needs to have a label on each line, and then these will be attached to the running container.

This line creates two labels in the file, one for the user and the second assigning a role.

echo 'user=123461' >> labels && echo 'role=cache' >> labels

The --label-file=<filename> option will create a label for each line in the file.

docker run --label-file=labels -d redis