Kubernetes Annotations and Labels: What’s the Difference?

Both labels and annotations are ways to attach metadata to objects in Kubernetes. But when should you use one versus the other?

The Kubernetes documentation is somewhat opaque on this subject:

Labels are key/value pairs that are attached to objects, such as pods. Labels are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system. Labels can be used to organize and to select subsets of objects. Labels can be attached to objects at creation time and subsequently added and modified at any time … Labels allow for efficient queries and watches and are ideal for use in UIs and CLIs. Non-identifying information should be recorded using annotations.

The definition of annotations is shorter, but still somewhat mysterious:

[Use] Kubernetes annotations to attach arbitrary non-identifying metadata to objects. Clients such as tools and libraries can retrieve this metadata.

The actual difference between annotations and labels is actually quite simple:

The actual difference between annotations and labels is actually quite simple:

Labels are for Kubernetes, while annotations are for humans.

Tweet this.

What Are Labels in Kubernetes?

Labels are used in conjunction with selectors to identify groups of related resources. Because selectors are used to query labels, this operation needs to be efficient. To ensure efficient queries, labels are constrained by RFC 1123. RFC 1123, among other constraints, restricts labels to a maximum 63 character length. Thus, labels should be used when you want Kubernetes to group a set of related resources.

What Are Annotations in Kubernetes?

Annotations are used for “non-identifying information” i.e., metadata that Kubernetes does not care about. As such, annotation keys and values have no constraints. Thus, if you want to add information for other humans about a given resource, then annotations are a better choice.

Example of Using Annotations and Labels

The following simple example uses both annotations and a selector. The annotations are used to add information about the Kubernetes service for humans and are not used by Kubernetes. The selector is used by the Kubernetes service to identify resources that the service will route to.

apiVersion: v1
kind: Service
metadata:
 name: quote
 annotations:
   a8r.io/owner: “@sally”
   a8r.io/repository: "https://github.com/ambassadorlabs/k8s-for-humans/"
spec:
 ports:
 - name: http
   port: 80
   targetPort: 8080
 selector:
   app: quote