What is the difference between. annotations and labels in in Kubernetes?

Question

I'm trying to wrap my head around the difference between annotations and labels.

My understanding of annotations is that it is metadata that adds key-value pairs that cannot be used by Kubernetes for identifying/filtering the resource.

Labels on the other hand are metadata key-value pairs that can be used by Kubernetes to identify/filter the resource.

Is this right? If this is so, then what is the practical use of annotations? Is it something to do with performance? Where labels are under the scanner of Kubernetes for filters and annotations are purely for adding metadata that is just informational?

But I've seen in cases where deployments needing Nginx or ingress capabilities using annotations. Then how does this get searched or used. Why are labels not used here instead?

When do we use annotations over labels and vice-versa? What are the pros and cons of each?

My understanding is rather limited here, however reading the official docs has not really helped me understand the use case of when do I use annotations vs labels.

Answer 1

Labels are metadata assigned to objects for identification purposes. For instance, a service selects the backend pod using the labels on pods.

Annotations are additional metadata that can be open-ended. It may be used for documentation purposes, or it can be used for configuring an object. For instance, the Nginx ingress controller reads those annotations on the running pod and uses them to configure the underlying NGinx instance. How annotations are used is completely up to the implementation.

Answer 2

Labels are indexed in Etcd and can be searched on. Annotations cannot.

Answer 3

Labels are key/value pairs that can be attached to Kubernetes objects such as Pods and ReplicaSets. They can be arbitrary, and are useful for attaching identifying information to Kubernetes objects. Labels provide the foundation for grouping objects.

Annotations, on the other hand, provide a storage mechanism that resembles labels: annotations are key/value pairs designed to hold nonidentifying information that can be leveraged by tools and libraries.

-- Kubernetes up & running, Chapter 6

Labels are used to identify resources

Examples of what labels can do:

• find all pods that have a value associated with the key

  kubectl get pods -l key=val,key2=val2

• merge and stream logs of the various pod that share the same label

  kubectl logs -l key=val

The reason why labels are used as selectors as opposed to annotations is because most Kubernetes implementation index labels in etcd.

Annotations are used to store data about the resource itself

This usually consists of machine-generated data, and can even be stored in JSON form.

Examples:

• last updated
• managed by
• sidecar injection configuration etc

Answer 4

Labels have additional limitations as explained here: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set

Valid label value:

must be 63 characters or less (can be empty), unless empty, must begin and end with an alphanumeric character ([a-z0-9A-Z]), could contain dashes (-), underscores (_), dots (.), and alphanumerics between.

So if it is a simple value you can set it as a label, if it's a URL or more complex value then store it as metadata / annotation.

The search syntax is also different for labels and annotations.

Answer 5

I would like to add my perspective to understand better.

Labels - Key-value pairs that you can associate with any K8s object. It is meant to be consumed by developers or Admins to select or filter objects.

Example:

• Select all pods with a specific value and bring them down.

Annotation - Key-value pairs that you can associate with any K8s object. This is not meant to be used by devs/admins and is not queryable. It is primarily used by the object to configure itself. Just to compare this with Java/Spring App Development, It's like passing some spring properties that is used by one of the Spring beans to configure itself.

Example:

• Role to be used by the Service Account
• Target type or port to be used by Ingress Object.