Monday, 6 June 2016

The Joy Of Organising. Container Image Labeling

Labelling is the new black

In Docker v1.6, Redhat contributed a way to add metadata to your Docker container images using labels. This was a great idea - a standard way to add stuff like notes or licensing conditions to an image. In fact, the only problem with labels is they aren’t used more (<20% of the time by some estimates). Gareth Rushgrove from Puppet has an interesting presentation on the concept

We decided we really needed to add labels to our Microscaling images so we did and here are our thought processes, the tools we wrote and our recommendations for how to do the “right thing”.

Schema and formatting

Labels are just free text key/value pairs, which is flexible but potentially messy -particularly as you can label an image or container multiple times (and containers inherit labels for their images)  and new keys will just overwrite any old keys with the same name.

  • Do namespace your keynames with the reverse DNS notation of your domain (e.g. com.mydomain.mykey) to avoid unplanned overwrites.
  • Don’t use com.docker.x, io.docker.x or org.dockerproject.x as the namespace in your keynames. Those prefixes are reserved.
  • Do use lowercase alphanumerics, . and - ([a-z0-9-.]) in keynames and start and end with an alphanumeric.
  • Don’t use consecutive dots and dashes in keynames.
  • Don’t add labels one at a time with individual label commands. Each label adds a new layer to the image so that’s inefficient. Try to add multiple labels in one call:
LABEL vendor=ACME\ Incorporated \ \"" \
      com.example.version="0.0.1-beta" \

These guidelines are not enforced, but we expect tools to come along to do that. 

Labels to Use

There has been much community discussion about default and orchestrator-specific labels (see references). We reviewed that and decided to add a very minimal initial set of labels to our own images:

"Labels": {
    "": "2016-06-03T19:17:49Z",
    "org.label-schema.docker.dockerfile": "/Dockerfile",
    "org.label-schema.license": "Apache-2.0",
    "org.label-schema.url": "",
    "org.label-schema.vcs-ref": "f03720f",
    "org.label-schema.vcs-type": "git",
    "org.label-schema.vcs-url": "",
    "org.label-schema.vendor": "Microscaling Systems"

(Updated 14 June 2016: These example labels were updated in this blog post to use a proposed common namespace - see note below).

Adding Labels to your DockerFile

Although you can just hardcode all these values into your Dockerfile, that’s a bit manual (because you can’t have dynamic labels in a Dockerfile). We therefore built a makefile to automate passing dynamic labels into our Dockerfile, which is checked into our GitHub repo.


The most controversial label in our opinion is license. Does an image have a single license? It might easily have multiple licences if you are building say a Ruby app on top of Alpine. We therefore expect the license label to potentially be multi-valued (comma separated), for example “Apache-2.0, GPL-3.0”

For consistency we used the approach that each license is a text string license Identifier as defined by SPDX

Go forth and label

It’s very easy to add your own labels to your images. Metadata is very useful  as a way to organise and track images, which can otherwise get pretty out of control!


Update 14 June 2016

After talking about these ideas with some folks across the container community, we're starting to work with them on a standardized label schema that we can all use in common. More details to follow very soon, but as a consequence of this we have started to use org.label-schema rather than our own namespace (com.microscaling) for some metadata, and we're updating this post to use that common namespace in the examples. If you'd like to get involved with the discussion of the standard label schema straight away, please let us know on @microscaling.

No comments:

Post a Comment