Let’s Organise - Label Container Images
Back in June we decided we really needed to add labels to our Docker container images — after all we are MicroBadger, which is all about labelling containers.
Metadata is a vital part of organising your container images — in the long term you’ll have lots of them and you need to know something about what they’re for. What kind of chaos would the world be in without the Dewey Decimal System?
So we added labels 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.
So here are Docker’s rules
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.is-beta= \
com.example.is-production=”” \
com.example.version=”0.0.1-beta” \
com.example.release-date=”2015–02–12"
These guidelines are not enforced, but we expect tools to come along to do that (e.g. Gareth Rushgrove of Puppet’s tool)
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, which matches the draft schema specification defined at http://label-schema.org
“Labels”: {
“com.microscaling.build-date”: “2016–06–03T19:17:49Z”,
“com.microscaling.dockerfile”: “/Dockerfile”,
“com.microscaling.license”: “Apache-2.0”,
“com.microscaling.url”: “https://microscaling.com",
“com.microscaling.vcs-ref”: “f03720f”,
“com.microscaling.vcs-type”: “git”,
“com.microscaling.vcs-url”: “git@github.com:microscaling/microscaling.git”,
“com.microscaling.vendor”: “Microscaling Systems”
}
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.
Licensing
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 http://spdx.org/licenses/
Go Forth and Label — and Tell Folk!
It’s very easy to add your own labels to your images. Metadata is an extremely useful as a way to organise and track images, which can otherwise get pretty out of control! And tell other folk to label using label-schema.org and MicroBadger . It’s the right thing to do. Let’s organize!
References
Gareth Rushgrove — DockerCon EU — https://speakerdeck.com/garethr/shipping-manifests-bill-of-lading-and-docker-metadata-and-container
Docker Label Guidelines — https://docs.docker.com/engine/userguide/labels-custom-metadata/
OpenShift — Labels for orchestration with Kubernetes -https://docs.openshift.com/enterprise/3.0/creating_images/metadata.html
Project Atomic — Proposal for generic labels — https://github.com/projectatomic/ContainerApplicationGenericLabels
Anne Currie is the CTO of Microscaling Systems, home of MicroBadger. We advocate more effective container use with metadata. Let’s organise! At http://microbadger.com & we are helping to develop a draft label schema at label-schema.org
If you liked this article, please hit the Recommend button below so that others might be more likely to find it. And if you’re using containers, you should definitely check out MicroBadger to explore image metadata.
Follow Microscaling Systems on Twitter
Originally published at blog.microscaling.com on June 6, 2016.
