Table Of Contents
What Are Kubernetes Labels? When Do You Use Them? What Is The Difference Between Kubernetes Labels And Annotations? Kubernetes Best Practices To Know And Apply Right Away

Scalability is one of the main reasons for using Kubernetes. Yet, scaling Kubernetes systems can reduce visibility into critical components. To overcome this, you have to organize your Kubernetes resources in a way that helps you find and track them more easily.

The way to do this in Kubernetes is by tagging objects, such as pods and services. So, what do you use to tag K8s objects?

Kubernetes labels. Let’s discuss how they work, and cover best practices you can use to make your environment more efficient.

Table of Contents

What Are Kubernetes Labels? When Do You Use Them?

Kubernetes labels are key-value pairs that contain metadata and that you assign to objects to help identify them. Each object can have its own set of key-value labels. In addition, you can attach labels to objects when creating them, and then add or modify them whenever you choose.

Labels are useful for a variety of purposes, including to:

  • Identify objects by attributes that are meaningful for users (Kubernetes itself does not use labels).
  • Define and organize subsets of objects.
  • Find objects within a cluster.
  • Modify configurations in bulk.
  • Keep track of, allocate, and manage Kubernetes costs.

The following characteristics and syntax requirements apply to Kubernetes labels:

  • A key must be unique for a specific object.
  • The segment must have up to 63 characters, while the prefix can have up to 253 characters.
  • Unless its length is 0, it must have alphanumeric characters [a-z0-9A-Z] at the start and at the end.
  • Characters like dot (.), dashes (-), and underscore (_) are allowed (internally).
  • The prefix should be a sequence of DNS labels that are separated by a dot and preceded by a slash.

Incorporating the prefix enables you and automated system components, like kube-scheduler, or third-party tools, to manage resources.

The Cloud Cost Playbook

What Is The Difference Between Kubernetes Labels And Annotations?

A label attaches identifying metadata to items, while an annotation attaches non-identifying metadata. While labels can help you organize objects and find collections that meet certain criteria, annotations cannot identify or select objects.

An annotation can include small or large metadata that is structured or unstructured. It can also include characters not permitted in labels.

Yet, labels and annotations are similar in that they are both key-value maps. You can also attach either of them to Kubernetes objects. Clients and libraries can access both the identifying and non-identifying metadata in labels and annotations, respectively.

One more thing. Shared labels and annotations have the matching prefix Labels without this prefix are private to the user. This ensures shared labels will not conflict with custom user labels.

So, how do you ensure you label your Kubernetes objects as efficiently as possible to optimize querying and managing your K8s system?

Kubernetes Best Practices To Know And Apply Right Away

Apply the following Kubernetes labels best practices to improve your tagging:

1. Have a standard labeling system

A consistent labeling convention ensures everyone in your company and the libraries and tools you use can use the labels for the intended purpose. Standard label schemas make it easier to organize, query, and filter Kubernetes resources across different teams, resources, and use cases.

One example is to avoid using the same label key but with different meanings. In this scenario, automated processes may fail and your teams may lack consensus. Another example is to use a set of labels that satisfy the deployment, reporting, and compliance standards of your organization’s stakeholders.

Ultimately, label items using intuitive language across a team or organization to make identifying the items easier and faster.

2. Start with recommended labels

You can group Kubernetes resources using a variety of K8s-recommended labels. Some common labels in Kubernetes include:

  • Name (such as “Nginx”)
  • The owner (such as, “Erik Peterson”)
  • Instance (such as “backend-blue”)
  • Managed-by (the tool managing it, such as “helm”)
  • Component (such as “database”)
  • Environment (such as “development”)
  • Version (such as “1.2.1”)
  • Business unit (such as “engineering”)

Remember, the prefix distinguishes the recommended labels from your custom labels. For a few examples, K8s recommends and labels to identify application names and components, respectively.

3. Follow correct syntax to build consensus

A quick reminder. The segment must have up to 63 characters, while the prefix can have up to 253 characters. The prefix should be a sequence of DNS labels that are separated by a dot and preceded by a slash.

Using the right syntax, just like using a standard label-naming system, ensures consistency, which supports effective communication within your teams. The consistency also enables you to use the cluster with libraries and client tools like kubectl, helm, and operators. Hence, we recommend picking a prefix for the company and sub-prefixes for projects.

4. Understand Equality and Set selections

These are the two label-selection options in Kubernetes. When you select objects by equality, you can retrieve those with labels equal or not equal to a certain value(s).

Based on the syntax, “=” and “==” represent equality, whereas “!=” denotes inequality. You are free to use multiple labels provided you separate them with commas and match all conditions. But if you want to find resources with multiple values simultaneously, you can use set-based selections. Sets function similarly to the IN keyword for SQL.

5. Label. Label. Label.

The more resources you label, the more visibility you will have into your Kubernetes application. So, while you don’t need a perfect labeling strategy to organize your Kubernetes objects, you’ll want to label as many resources as you can. When you group them together like this, querying for all resources with a specific label is much faster.

6. Short and sweet does it

Keeping label keys short and in lowercase eases reading and understanding what it’s about. Even if you have many labels, which is common for scalable Kubernetes, your labels won’t add up too much.

7. Add necessary labels to pod templates

For labels you consider essential, adding them to pod templates lets K8s controllers generate pods that have the consistent state you want. The templates make up workload resources, like DaemonSets and Deployments. To begin, add only a few labels to the template, such as owner, environment, and component labels.

8. Improve release management with labels

You can use labels to group and filter the apps running on your Kubernetes. Take a backend service running multiple pods bearing the labels version:v1 and app:backend, for example. You are free to use new backend instances in the cluster; switch the service label selector to version:v2 and app:backend.

All requests sent to the backend service will now reach the v2 instances. If you want to go back to v1, you’ll need to just change the service specification. In addition, this Blue/Green deployment strategy allows you to conduct A/B tests and canary releases more easily.

9. Avoid storing privileged information on labels

Any sensitive information you store in labels will be accessible in plain text to anyone with access to your Kubernetes cluster. So, including passwords and API keys on labels can expose them to security threats, including data breaches.

Labels are not safety nets — RBAC is. Anyone with access to the cluster can change them. So, labels are not ideal as security controls; they simply organize and identify Kubernetes objects and annotations add arbitrary metadata. A more secure approach is to use security tools like Role-based Access Control (RBAC) or network policies.

10. Likewise, avoid relying solely on labels to identify resources

Because anyone with cluster access can easily change labels, you want to use them as an additional identifying mechanism — not the only one. If someone changes the label from “staging” to “development”, in a flash, staging resources change into development resources. Using namespaces, selectors, and annotations are other ways to identify Kubernetes items.

11. Refrain from making unnecessary modifications to labels

The effects of changing labels can be far-reaching, even if they are unintended, depending on what changes you make. Take for example changing the “app” label on a series of pods from “backend” to “frontend”.

The pods could crash and become unavailable when Kubernetes reschedules them to run on nodes that aren’t meant to run the “backend” app. Be sure to weigh any changes and ensure they are absolutely necessary before making any.

12. Use a robust platform to organize resource insights even with messy tags

Consistently tagging resources with the right labels is time-consuming and challenging, especially at scale. An advanced Kubernetes cost optimization platform can help you fill in the gaps where your labels are less than perfect.

The CloudZero platform, for example, works like an observability solution rather than just a cost tool.

With CloudZero’s code-driven approach, you can aggregate Kubernetes consumption and cost data from across your entire environment. CloudZero then enriches, normalizes, and analyzes additional metadata it collects from your apps and infrastructure.


This approach provides accurate insight into Kubernetes resource usage and costs for tagged, untagged, and untaggable resources. You can also collect, understand, and share cost insights from resources you run in multi-tenant environments.

Kubernetes Complete Cost

In addition, CloudZero gives you granular Kubernetes cost information, such as:

  • Cost per pod
  • Cost per namespace
  • Cost per cluster

You can also capture, understand, and report on Kubernetes costs by:

  • Cost per customer
  • Cost per environment
  • Cost per product or product feature
  • Cost per Kubernetes deployment or project
  • Cost per team or business unit, and more.

You can also prevent overspending by getting timely alerts from CloudZero about specific code changes that cause cost anomalies.

This is how CloudZero has helped customers like Drift (reduced annual cloud costs by $2.4 million), Remitly (allocated 50% more costs without tagging), Validity (now spends 50% less time managing costs), and Obsidian (reduced their AWS costs by 25%). You can too.

to see the power of CloudZero for yourself!

The Cloud Cost Playbook

The step-by-step guide to cost maturity

The Cloud Cost Playbook cover