Labels and Annotations in Kubernetes

What’s the difference between labels and annotations?

At first glance, both seem to be simple key-value pairs, meant to add metadata to a Kubernetes setup. The distinction is easy to explain, but takes a bit of time to understand from the docs.

Labels

Contain identifying information and are a used by selector queries or within selector sections in object definitions. The structure of keys as well as values is constrained. This way, queries can be evaluated quickly, using optimized data structures and algorithms.

From the labels docs:

We don’t want to pollute labels with non-identifying, especially large and/or structured, data. Non-identifying information should be recorded using annotations.

Annotations

Are used for non-identifying information. Stuff not used internally by k8s. You can’t specify selectors over them within Kubernetes, but they can be used by external tools and libraries. As the internal performance of Kubernetes is not negatively impacted by huge annotations, the keys and values are not constrained like labels are.

From the annotations docs:

The metadata in an annotation can be small or large, structured or unstructured, and can include characters not permitted by labels.

Next Steps

If you need to point Kubernetes to a group of resources, labels are the way to go. Make sure that the data you have in mind abides by the constraints.

If you want to annotate your setup with data which will help people or tools, but not Kubernetes itself, it’s better to put it into annotation meta data.

Could your current workflows benefit from having direct access to something like timestamps, commit SHAs or the name of the person who is responsible for certain resources? Just add an annotation step to your current deployment pipeline.