9 Best Practices and Examples for Working with Kubernetes Labels

Kubernetes labels allow DevOps teams to identify, select and operate on Kubernetes objects. In this blog post we outline 9 best practices for working with Kubernetes Labels and examples for Kubernetes label keys and values

Hasham Haider

Hasham Haider

September 28, 2018

11 minute read

Kubernetes has a lot of nifty built-in features. Kubernetes labels are one of them. Kubernetes labels allow DevOps teams to identify Kubernetes objects and organize them into groups. One good use-case of this is grouping pods based on the application they belong to. Teams can also develop any number of labeling conventions including ones to group pods by environment, customer, team/owner or release version.

But that is just the start; Kubernetes labels pack a lot of other functionality. For example, it is possible to do bulk operations in Kubectl, by filtering a large number of resources, using Kubernetes labels. Kubernetes deployments also use labels to identify the pods that they manage. Similarly, Kubernetes services and replication controllers use labels to refer to a set of pods. Recommended Kubernetes labels also support querying and interoperability between Kubernetes tools.

Below we take a look at some best practices for Kubernetes labels.

1. Beware of the Syntax

Make sure that you get the syntax right. Below is an overview of the Kubernetes labeling syntax. There are 3 things you have to consider; label key (label prefix, label name) and label value.

  • Label Key
    • Label prefix
      • Label prefix is optional
      • Label prefixes can be no longer than 253 characters
      • Label prefix must be a DNS subdomain
      • Label prefix can also be a series of DNS subdomains, separated by “.”
      • Label prefixes have to end with “/”
    • Label name
      • Label name is required
      • Label names can be up to 63 characters
      • Characters have to be alphanumeric characters
      • Label names can also include “-”, “_” and “.”
      • Label names have to begin and end with an alphanumeric character
  • Label value
    • Label values can be up to 63 characters long
    • Characters have to be alphanumeric characters
    • Label values can also include “-”, “_” and “.”
    • Label values have to begin and end with an alphanumeric character

2. Label, Label, Label

The first rule of Kubernetes labeling is to actually do it, Always!

Creating or attaching Kubernetes labels should be second nature whenever new objects are created. Holding regular labeling audits for resources already in operation, to ensure they are labeled, is also good practice.

It might slow you down in whatever you are currently creating, but believe me: Taking the time and labeling everything as you work on the project will pay off later.

Labeling resources and objects will help you avoid Kubernetes production pain down the line. It will also make it easier to do operations in bulk on Kubernetes objects. One example of this is using Label selector to spin up Kubernetes deployments and services by selecting pods based on their labels.

Create a pod with labels “environment=staging” and “team=kube-team” in Kubectl:

apiVersion: v1
kind: Pod
 name: my-pod
   environment: staging
   team: kube-team
   - name: my-container
     image: "k8s.gcr.io/my-app:v0.1"
        cpu: 1

Check that the labels are applied in the newly created pod:

kubectl get pod my-pod --show-labels

Add a label to a pod using Kubectl:

kubectl label pod my-pod versionID=ver0.9

Remove a label from a pod using Kubectl:

kubectl label pod my-pod versionID-

Update a label for a pod using Kubectl:

kubectl label --overwrite pods my-pod team=ops

3. Create company-wide consensus on labeling conventions

Since labels are meant to be meaningful and relevant for both Kubernetes itself and DevOps teams it is essential to develop consensus on labeling conventions. Sit down with your DevOps team and come-up with standard labeling conventions for Kubernetes resources. Also, ensure that conventions propagate across team and organizational boundaries.

4. Create a list of required labels

Some people just do not get with the times. For them, come up with a list of labels that have to be defined whenever a kubernetes pod is created. Start off small with 3-4 labels per object. You can follow Zalando's example, who require every Kubernetes resource to have application ID, version, owner, stage and release labels.

You can add required labels by leveraging pod templates. Pod templates are manifests that are used by Kubernetes controllers to create pods.

Below is a pod template with Kubernetes labels of application ID, version, stage, release and owner.

apiVersion: v1
kind: Pod
 name: my-pod
   application-ID: my-app
   version: version-nr
   stage: dev
   release: release-nr
   owner: team-kube

logos of docker, mesos, and kubernetes and a green button

5. Create a more extensive list of Kubernetes labels

Don't stop once you have a list of required labels. While you are on a roll keep it going. Create a more extensive list with labels that can provide more operability and context to your objects. Following is an exhaustive list of Kubernetes labels examples, along with their example values. Take your pick:

Label Example Key


Label Example value


The name of the application or its ID



The version number



The team or individual the object belongs to



The stage or phase

Dev, staging, QA, Canary, Production


The release number



Which tier the app belongs to



Is the resource part of an app that is customer facing?



What roles does the app have



The associated project ID



The customer ID for the resource


6. Use recommended Kubernetes labels

Kubernetes also provides a list of recommended labels. These labels are recommended for every object that you create and have a shared prefix; app.kubernetes.io. Prefixes ensure that recommended labels do not get mixed up with custom labels defined by users.

Recommended labels include:







Below is an example pod with example values for recommended Kubernetes labels:

apiVersion: v1
kind: Pod
    app.kubernetes.io/name: my-pod

    app.kubernetes.io/instance: Auth-1a
    app.kubernetes.io/version: “2.0.1”
    app.kubernetes.io/component: Auth
    app.kubernetes.io/part-of: my-app
    app.kubernetes.io/managed-by: helm

7. Monitor pre-populated Kubernetes labels

Kubernetes also generates a list of pre-populated labels that are attached either exclusively to nodes or both to nodes and persistent volumes. Pre-populated labels can be used in a number of ways e.g. when targeting workloads to specific instance types or spreading pods in a replication controller or service, across multiple cloud provider zones.

Node specific labels include:



  • Populated with the OS type e.g Linux


  • Populated with the hostname


  • Populated with the cloud provider instance type e.g. t2.medium

Labels that are pre-populated for both Nodes/persistent volumes:


  • Populated with the cloud provider region e.g. eu-west-1


  • Populated with the cloud provider zone e.g. eu-west-1b

8. Specify Cloudlabels and NodeLabels in Kops

Kops is a tool for deploying and managing highly available Kubernetes clusters. DevOps teams can specify two types of labels in Kops; CloudLabels and Nodelabels. Both these labels are specified at the InstanceGroup level. Kops InstanceGroups are similar to AWS autoscaling groups.

Once you apply CloudLabels to an InstanceGroup, they are applied to all the instances that are part of the InstanceGroup and show up on your AWS console as AWS tags. These can then be used to do cost allocation and chargeback.

Examples of CloudLabels that are recommended for cost allocation include application name, cost center, stack (test, prod), owner (team), customer and project. NodeLabels are the same as Kubernetes labels and are applied to Kubernetes nodes.

9. Differentiate between Kubernetes labels vs annotations

Kubernetes labels and annotations are both ways of adding metadata to Kubernetes objects. The similarities end there, however. Kubernetes labels allow you to identify, select and operate on Kubernetes objects. Annotations are non-identifying metadata and do none of these things.

Annotations allow you to add non-identifying metadata to Kubernetes objects. Examples include phone numbers of persons responsible for the object or tool information for debugging purposes. In short, annotations can hold any kind of information that is useful and can provide context to DevOps teams.


Kubernetes labels are a great way of identifying and organizing Kubernetes objects and resources. Kubernetes team leads and IT managers are best placed to develop and implement Kubernetes labeling plans. By ensuring labeling conventions are followed across teams, they can tame Kubernetes environments and prevent sprawl. Since Labels make it easier to operate on Kubernetes objects in bulk, adhering to labeling conventions will also make teams more productive in the long run.

To recap here is a list of Kubernetes labels best practices: 

  • Beware of the Syntax
  • Use the following recommended Kubernetes labels
  • Monitor pre-defined Kubernetes labels
  • Specify Cloudlabels and NodeLabels
  • Differentiate between Kubernetes labels vs annotations
  • Label, Label, Label
  • Create company-wide consensus on labeling conventions
  • Create a list of required Kubernetes labels
  • Create a more extensive list of Kubernetes labels

Want to analyze Kubernetes costs and allocate them to individual teams and applications? Download the Kubernetes Cost Analysis and Allocation Ebook for AWS

Download Ebook

Kubernetes Production Readiness and Best Practices Checklist Kubernetes Production Readiness and Best Practices Checklist Cover Download Checklist
Hasham Haider


Hasham Haider

Fan of all things cloud, containers and micro-services!

Want to Understand How Cloud Infrastructure Drives your Kubernetes Costs and Identify Optimization Opportunities?

Request a quick 20 minute demo to learn how best to leverage cloud VM’s for your Kubernetes clusters and make infrastructure cost savings of up to 30% using Replex.io.

Contact Us