Summary

The provided content is a guide on how to use Docker labels, which are key-value pairs for attaching metadata to Docker images and containers without affecting their functionality.

Abstract

Docker labels serve as a means to attach custom metadata to various Docker entities such as images, containers, networks, and volumes. This guide explains the concept of Docker labels, their uses, and how to apply them at both the image and container level. It demonstrates the process of creating a Dockerfile with labels, building an image with specified label values, and running containers with labels. The guide also covers how to inspect labels for introspection and filtering, showcasing practical applications like identifying the build date of an image or categorizing containers based on their role (e.g., primary or secondary nodes).

Opinions

The author suggests that labels are versatile and can be used for a variety of purposes, such as indicating the git commit of an image source, organizing images by project or component, and distinguishing between containers created from the same image.
The guide implies that labels enhance the manageability of Docker resources by allowing users to attach meaningful and searchable information.
The author demonstrates a preference for using labels to maintain clarity and organization within Docker environments, emphasizing their utility in filtering and inspecting containers based on custom criteria.
The provision of a practical example using a Dockerfile and the subsequent building and running of an image with labels indicates the author's view that hands-on demonstration is an effective way to convey the concept and benefits of using Docker labels.

Docker Labels and How to Use Them

In this guide, I’ll explain what Docker labels are, what can you use them for, and how to set them on image and container level.

What are the Labels?

Labels are key-value pairs you can attach to almost everything in Docker. You define both keys and values for the labels.

Labels are metadata, meaning they don’t affect the functionality or configuration of the image or container, but you can inspect them. You can put them on images, containers, networks, volumes, etc.

There’s lots of different use case for labels, including, but not limited to the following:

you can label an image with git commit from which it was built;
labels can be used for organizing your images: you can label images from different projects using their project name as the label value;
you can label images containing different components (Java application, tools, database, proxy server, etc.) — also, for organizing stuff;
you can label containers, created from the same image, with different labels, e.g. primary and secondary nodes.

Labeling Images

To demonstrate the labeling on images, I’ll create the following simple Dockerfileand build an image out of it:

FROM busybox
ARG buildDate
LABEL buildDate=$buildDate

The first line of the file means that we’re going to create an image based on the busybox — a tiny distribution providing a command line and all usual UNIX command-line utilities.
The second line, starting with ARG, defines an argument that is expected during the build time.
The third line, starting with LABEL, sets a label for this image. The label value will be provided from the command line during the build as the buildDate argument. Its value will be substituted instead of the placeholder.

I now build an image based on this Dockerfile:

$ docker build --build-arg buildDate=$(date +'%Y-%m-%d') \
  --tag mybusybox .

Sending build context to Docker daemon  3.072kB
Step 1/3 : FROM busybox
 ---> c7c37e472d31
Step 2/3 : ARG buildDate
 ---> Using cache
 ---> c2a728dac3b5
Step 3/3 : LABEL buildDate=$buildDate
 ---> Using cache
 ---> 87ff4bb6d5a0
Successfully built 87ff4bb6d5a0
Successfully tagged mybusybox:latest

I provided the buildDate argument, which was expected by the Dockerfile, using the command line parameter --build-arg. To set the value for this parameter, I used the output of the date +'%Y-%m-%d' command. This command prints out the current system date in the specified format.

I will now create a container out of this newly built image, specifying the name for the container, for simplicity of access:

docker run --name mybusybox-container mybusybox

To get the label from the running container, I now run the following command:

$ docker inspect --format='{{.Config.Labels.buildDate}}' \
  mybusybox-container

2020-07-23

The docker inspect command allows me to inspect the running container, and the --format key — to filter the required information. In this case — the exact value of the label.

Now I can always get the image build date, whenever I inspect the container that’s created from the image. However, this label will always be the same for all containers built from the image.

Labeling Containers

Now I’ll show how to use different labels for specific containers. I’ll create three containers from our image with different labels: one with the type=primary label, and two with type=secondary label:

$ docker run --name mybusybox-container-1 \
  --label type=primary mybusybox
$ docker run --name mybusybox-container-2 \
  --label type=secondary mybusybox
$ docker run --name mybusybox-container-3 \
  --label type=secondary mybusybox

I can now inspect the labels on these containers in the same way as with image labels:

$ docker inspect --format='{{.Config.Labels.type}}' \
  mybusybox-container-1

primary

$ docker inspect --format='{{.Config.Labels.type}}' \
  mybusybox-container-2

secondary

$ docker inspect --format='{{.Config.Labels.type}}' \
  mybusybox-container-3

secondary

Inspecting the labels is not the only thing I can do with them — I can also use labels for filtering. For example, I can list all containers with secondary label like this:

Wrapping Up

I hope this simple guide helps you with using Docker labels and also shows some practical ideas on how to use them. More information on labels is available in the Docker documentation.