Docker Labels

Open Container Initiative - Annotations

We will adopt the label schema defined by the Open Container Initiative so that we all use the same naming convention.

Every attempt should be made to include as many of these labels as possible in your Dockerfile -

• org.opencontainers.image.created date and time on which the image was built
• org.opencontainers.image.authors contact details of the people or organization responsible for the image (freeform string)
• org.opencontainers.image.url URL to find more information on the image (string)
• org.opencontainers.image.documentation URL to get documentation on the image (string)
• org.opencontainers.image.source URL to get source code for building the image (string)
• org.opencontainers.image.version version of the packaged software
• org.opencontainers.image.revision Source control revision identifier for the packaged software.
• org.opencontainers.image.vendor Name of the distributing entity, organization or individual.
• org.opencontainers.image.licenses License(s) under which contained software is distributed.
• org.opencontainers.image.ref.name Name of the reference for a target (string).
• org.opencontainers.image.title Human-readable title of the image (string)
• org.opencontainers.image.description Human-readable description of the software packaged in the image (string)

If these are not sufficient, we can define additional vendor-specific labels as needed.

Static vs Dynamic

Most of the labels are static in nature and can be hard-coded to predefined strings in the Dockerfile (for example: org.opencontainers.image.title).

Some are dynamic and need to be passed in as arguments to the Dockerfile (for example: org.opencontainers.image.created).

Example

Here are some sample snippets that show how labels are used:

    docker build --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') -f dockerfile -t my-container-image .

FROM gcc:7

ARG BUILD_DATE

#Labels
LABEL org.opencontainers.image.title="AA Base Container Image" \
      org.opencontainers.image.description="AA Base Container Image to be used in multi-stage builds" \
      org.opencontainers.image.vendor="Sensia Global" \
      org.opencontainers.image.authors="Vivek Chinta <vchinta1@sensiaglobal.com>" \
      org.opencontainers.image.created="$BUILD_DATE"

Docker Inspect

The ‘docker inspect’ command can be used to dump the labels associated with a given image, shown here:

user@ubuntu1804vm:~/advapps/depSrc/docker-build$ docker inspect 1fe9682aeb60 | grep "Labels" -A 10
            "Labels": {
                "org.opencontainers.image.authors": "Vivek Chinta <vchinta1@sensiaglobal.com>",
                "org.opencontainers.image.created": "2020-07-22T05:28:17Z",
                "org.opencontainers.image.description": "AA Base Container Image to be used in multi-stage builds",
                "org.opencontainers.image.title": "AA Base Container Image",
                "org.opencontainers.image.vendor": "Sensia Global",
            }
...