Labels are key-value pairs that are attached to Kubernetes objects, such as Pods. They are intended to be used to specify object attributes which are meaningful and relevant to users, while not directly impacting implying semantics of the core system. A common use case is using labels to organize or select a subset of Kubernetes objects. They can be attached at creation, as well as added / modified later. Each key in the label object must be unique for that given resource.

"labels": {
  "keyA": "valueA",
  "keyB": "valueB"

Eventually, these labels are indexed (and reverse-indexed) in order to make queries and watches more efficient. Labels are also used in UIs and the CLI to organize resources. Labels are not meant to hold non-identifying, large, or unstructured data. Instead, annotations should be used for such data.


Labels enable end users to map their own, custom, organizational structures onto system resources in a loosely coupled fashion. 

Labels can be used to identify resources in a variety of ways. Some examples include:

  • release -  stable, release, or canary
  • environment - dev, QA, production
  • tier - frontend, backend, cache
  • partition - customerA, customerB
  • track - daily, weekly

These are simple examples of commonly used labels; you are free to specify any value you wish, and create your own conventions.

Syntax & Character Set

Valid label keys have two segments: an optional prefix and name, which are separated by a slash. The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character. The segment can also contain dashes, underscores, and periods. The prefix segment is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by periods no longer than 253 characters. If the prefix is omitted, the label key is presumed to be private to the user. Automated system components such as kube-scheduler, kube-controller-manager, kube-apiserver, kubctl, and other third-party tooling which add labels to end-user objects, are required to specify a prefix. The prefix is reserved for Kubernetes core components.

Valid label values must be 63 characters or less, beginning and ending with an alphanumeric character. The value can also contain dashes, underscores, and periods.

Label Selectors

Unlike names and UIDs, labels do not provide uniqueness. In fact, we expect many objects to posses the same labels. Through the use of a label selector, a client can select a set objects. Label selectors are the core grouping primitive in Kubernetes. Currently, the API supports two different types of selectors: equality-based and set-based. Label selectors can be comprised of multiple requirements which are comma separated. The comma delimiter acts as a logical AND operator, so all requirements must be satisfied. An empty label selector selects all objects in the collection, and a null label selector selects no objects. It is important to note that label selectors of two controllers must not overlap within a given namespace, otherwise they will fight with one another.

Equality-Based Selection

Equality and inequality based requirements allow resource filtering by label keys and values. All matching objects must satisfy all of the provided label constraints, though they may contain additional labels. There are three allowed operators: = , == , and != ; the first two represent equality based selection, while the last represents inequality.

The following example will select all resources where key environment is equal to production :

environment = production

Whereas the following example will select all resources where either the tier label key does not exist, or has a value other than frontend :

tier != frontend

Taking it a step further, one could select all resources in production , excluding frontend by using the comma operator:


Set-Based Selection

Set based label requirements allow filtering keys according to a set of values. Three kinds of operators are supported: in , notin , and exists

The following example selects all resources where key environment is equal to production  or qa :

environment in (production, qa)

The following example selects all resources where the tier label key does not exist, or has a value other than frontend  or backend :

tier notin (frontend, backend)

The following example selects all resources where the partition  keys exits, regardless of the value:


The following example selects all resources where the partition  key does not exist:


Similar to equality-based selection, the comma separator acts as an AND  operator. Filtering resources with a partition key (regardless of value), with environment value other than qa can be achieved by specifying the following: 

partition,environment notin (qa)

The set-based label selector is a general form of equality since environment=production is equivalent to environment in (production); similarly for != and notin.

Set-based requirements can be mixed with equality-based requirements. For example:

partition in (customerA, customerB),environment!=qa


List and Watch Filtering

Both LIST and WATCH operations may specify label selectors to filter the sets of objects returned using a query parameter. Both types of requirements are permitted and demonstrated below:

  • equality-based requirements - ?labelSelector=environment%3Dproduction,tier%3Dfrontend 
  • set-based requirements - ?labelSelector=environment+in+%28production%2Cqa%29%2Ctier+in+%28frontend%29 

Similarly, both label selector styles can be used to list or watch resources via a REST client. For example, using an equality based selector with kubectl may look like:

$ kubectl get pods -l environment=production,tier=frontend

The same query can also be executed using set-based requirements:

$ kubectl get pods -l 'environment in (production),tier in (frontend)'

As previously mentioned, set based requirements are more expressive. For instance, they can implement the OR operator on values as shown below:

$ kubectl get pods -l 'environment in (production, qa)'

Or they can restrict negative matching via the exists  operator:

$ kubectl get pods -l 'environment,environment notin (frontend)'

Set References in API Objects
Some Kubernetes objects, such as services and replication controllers, leverage label selectors to specify sets of other resources, such has pods.

The set of pods that a service targets is defined with a label selector. Similarly, pods managed by a replication controller are specified via label selector.

The selectors for both objects are defined in json or yaml format, using maps, where only equality-based requirement selectors are supported.

In JSON this may look like:

"selector": {
    "component" : "nginx"

or in YAML as:

    component: nginx

This is equivalent to component=nginx  or component in (nginx) .

Newer resources such as Jobs, Deployments, ReplicaSets, and DaemonSets all support set-based requirements as well.

    component: nginx
    - {key: tier, operator: In, values: [cache]}
    - {key: environment, operator: NotIn, values: [dev]}

The matchLabels key is a map of key value pairs. A single key value pair in the map is equivalent to an element of matchExpressions , whose key field is the "key", the operator  is the "in", and the values  array containers only value . matchExpressions is a list of pod selector requirements. Valid operators include, In , NotIn , Exists , and DoesNotExist . The values set is required to be non-empty in the case of In and NotIn . All of the requirements, both in matchLabels as well as matchExpressions , are AND ed together, and must all be satisfied to match.

Did this answer your question?