DEV Community

Cover image for Labels and annotations in Kubernetes
Daniele Polencic
Daniele Polencic

Posted on

Labels and annotations in Kubernetes

In Kubernetes, you can use labels to assign key-value pairs to any resources.

Labels are ubiquitous and necessary to everyday operations such as creating services.

However, how should you name and use those labels?

Any resource in Kubernetes can have labels.

Some labels are vital (e.g. service's selector, operators, etc.), and others are useful to tag resources (e.g. labelling a deployment).

Examples of useful and useless labels in Kubernetes

Kubectl offers a --show-labels flag to help you list resources and their labels.

If you list pods, deployments and services in an empty cluster, you might notice that Kubernetes uses the component=<name> label to tag pods.

Retrieving labels from resources

Kubernetes recommends six labels for your resources:

  1. Name
  2. Instance
  3. Version
  4. Component
  5. Part of
  6. Managed By

Recommended labels for resources

Let's look at an excellent example of using those labels: the Prometheus Helm chart.

The charts install five pods (i.e. server, alter manager, node exporter, push gateway and kube state metrics).

Notice how not all labels are applied to all pods.

Prometheus Helm chart labels

Labelling resources properly helps you make sense of what's deployed.

For example, you can filter results with kubectl:



kubectl get pods -l "environment in (staging, dev)"


Enter fullscreen mode Exit fullscreen mode

The command above only lists pod in staging and dev.

Selecting resources that are tagged with labels

If those labels are not what you are after, you can always create your own.

A <prefix>/<name> key is recommended — e.g. company.com/database.

Custom label with prefixes

The following labels could be used in a multitenant cluster:

  • Business unit
  • Development team
  • Application
  • Client
  • Shared services
  • Environment
  • Compliance
  • Asset classification

Labels for multitenant cluster

Alongside labels, you have annotations.

Whereas labels are used to select resources, annotations decorate resources with metadata.

You cannot select resources with annotations.

Annotations in Kubernetes

Administrators can assign annotations to any workload.

However, more often, Kubernetes and operators decorate resources with extra annotations.

A good example is the annotation kubernetes.io/ingress-bandwidth to assign bandwidth to pods.

Annotating resources with ingress and egress bandwidth constraints

The official documentation has a list of well-known labels and annotations.

Here are some examples:

  • kubectl.kubernetesׄ.io/default-container
  • topology.kubernetes.io/region
  • node.kubernetes.io/instance-type
  • kubernetes.io/egress-bandwidth

Annotations are used extensively in operators.

Look at all the annotations you can use with the ingress-nginx controller.

There are several annotations available for the ingress-nginx controller

Unfortunately, using operators/cloud providers/etc. annotations is not always a good idea if you wish to stay vendor-neutral.

However, sometimes it's also the only option (e.g. having an AWS ALB deployed in the correct subnet when using a service of type LoadBalancer).

Annotations available on AWS and EKS

Here are a few links if you want to learn more:

And finally, if you've enjoyed this thread, you might also like:

Top comments (0)