Labels and Selectors

Labels are key/value pairs that are attached toobjects such as Pods.Labels are intended to be used to specify identifying attributes of objectsthat are meaningful and relevant to users, but do not directly imply semanticsto the core system. Labels can be used to organize and to select subsets ofobjects. Labels can be attached to objects at creation time and subsequentlyadded and modified at any time. Each object can have a set of key/value labelsdefined. Each Key must be unique for a given object.

"metadata": {"labels": {"key1" :"value1","key2" :"value2"  }}

Labels allow for efficient queries and watches and are ideal for use in UIsand CLIs. Non-identifying information should be recorded usingannotations.

Motivation

Labels enable users to map their own organizational structures onto system objectsin a loosely coupled fashion, without requiring clients to store these mappings.

Service deployments and batch processing pipelines are often multi-dimensional entities(e.g., multiple partitions or deployments, multiple release tracks, multiple tiers,multiple micro-services per tier). Management often requires cross-cutting operations,which breaks encapsulation of strictly hierarchical representations, especially rigidhierarchies determined by the infrastructure rather than by users.

Example labels:

• "release" : "stable","release" : "canary"
• "environment" : "dev","environment" : "qa","environment" : "production"
• "tier" : "frontend","tier" : "backend","tier" : "cache"
• "partition" : "customerA","partition" : "customerB"
• "track" : "daily","track" : "weekly"

These are examples ofcommonly used labels;you are free to develop your own conventions.Keep in mind that label Key must be unique for a given object.

Syntax and character set

Labels are key/value pairs. Valid label keys have two segments: an optionalprefix and name, separated by a slash (/). The name segment is required andmust be 63 characters or less, beginning and ending with an alphanumericcharacter ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.),and alphanumerics between. The prefix is optional. If specified, the prefixmust be a DNS subdomain: a series of DNS labels separated by dots (.),not longer than 253 characters in total, followed by a slash (/).

If the prefix is omitted, the label Key is presumed to be private to the user.Automated system components (e.g.kube-scheduler,kube-controller-manager,kube-apiserver,kubectl, or other third-party automation) which add labelsto end-user objects must specify a prefix.

Thekubernetes.io/ andk8s.io/ prefixes arereserved for Kubernetes core components.

Valid label value:

• must be 63 characters or less (can be empty),
• unless empty, must begin and end with an alphanumeric character ([a-z0-9A-Z]),
• could contain dashes (-), underscores (_), dots (.), and alphanumerics between.

For example, here's a manifest for a Pod that has two labelsenvironment: production andapp: nginx:

apiVersion:v1kind:Podmetadata:name:label-demolabels:environment:productionapp:nginxspec:containers:-name:nginximage:nginx:1.14.2ports:-containerPort:80

Label selectors

Unlikenames and UIDs, labelsdo not provide uniqueness. In general, we expect many objects to carry the same label(s).

Via alabel selector, the client/user can identify a set of objects.The label selector is the core grouping primitive in Kubernetes.

The API currently supports two types of selectors:equality-based andset-based.A label selector can be made of multiplerequirements which are comma-separated.In the case of multiple requirements, all must be satisfied so the comma separatoracts as a logicalAND (&&) operator.

The semantics of empty or non-specified selectors are dependent on the context,and API types that use selectors should document the validity and meaning ofthem.

Equality-based requirement

Equality- orinequality-based requirements allow filtering by label keys and values.Matching objects must satisfy all of the specified label constraints, though they mayhave additional labels as well. Three kinds of operators are admitted=,==,!=.The first two representequality (and are synonyms), while the latter representsinequality.For example:

environment = productiontier != frontend

The former selects all resources with key equal toenvironment and value equal toproduction.The latter selects all resources with key equal totier and value distinct fromfrontend,and all resources with no labels with thetier key. One could filter for resources inproductionexcludingfrontend using the comma operator:environment=production,tier!=frontend

One usage scenario for equality-based label requirement is for Pods to specifynode selection criteria. For example, the sample Pod below selects nodes wheretheaccelerator label exists and is set tonvidia-tesla-p100.

apiVersion:v1kind:Podmetadata:name:cuda-testspec:containers:-name:cuda-testimage:"registry.k8s.io/cuda-vector-add:v0.1"resources:limits:nvidia.com/gpu:1nodeSelector:accelerator:nvidia-tesla-p100

Set-based requirement

Set-based label requirements allow filtering keys according to a set of values.Three kinds of operators are supported:in,notin andexists (only the key identifier).For example:

environment in (production, qa)tier notin (frontend, backend)partition!partition

• The first example selects all resources with key equal toenvironment and valueequal toproduction orqa.
• The second example selects all resources with key equal totier and values otherthanfrontend andbackend, and all resources with no labels with thetier key.
• The third example selects all resources including a label with keypartition;no values are checked.
• The fourth example selects all resources without a label with keypartition;no values are checked.

Similarly the comma separator acts as anAND operator. So filtering resourceswith apartition key (no matter the value) and withenvironment differentthanqa can be achieved usingpartition,environment notin (qa).Theset-based label selector is a general form of equality sinceenvironment=production is equivalent toenvironment in (production);similarly for!= andnotin.

Set-based requirements can be mixed withequality-based requirements.For example:partition in (customerA, customerB),environment!=qa.

API

LIST and WATCH filtering

Forlist andwatch operations, you can specify label selectors to filter the sets of objectsreturned; you specify the filter using a query parameter.(To learn in detail about watches in Kubernetes, readefficient detection of changes).Both requirements are permitted(presented here as they would appear in a URL query string):

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

Both label selector styles can be used to list or watch resources via a REST client.For example, targetingapiserver withkubectl and usingequality-based one may write:

kubectl get pods -lenvironment=production,tier=frontend

or usingset-based requirements:

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

As already mentionedset-based requirements are more expressive.For instance, they can implement theOR operator on values:

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

or restricting negative matching vianotin operator:

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

Set references in API objects

Some Kubernetes objects, such asservicesandreplicationcontrollers,also use label selectors to specify sets of other resources, such aspods.

Service and ReplicationController

The set of pods that aservice targets is defined with a label selector.Similarly, the population of pods that areplicationcontroller shouldmanage is also defined with a label selector.

Label selectors for both objects are defined injson oryaml files using maps,and onlyequality-based requirement selectors are supported:

"selector": {"component" :"redis",}

or

selector:component:redis

This selector (respectively injson oryaml format) is equivalent tocomponent=redis orcomponent in (redis).

Resources that support set-based requirements

Newer resources, such asJob,Deployment,ReplicaSet, andDaemonSet,supportset-based requirements as well.

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

matchLabels is a map of{key,value} pairs. A single{key,value} in thematchLabels map is equivalent to an element ofmatchExpressions, whosekeyfield is "key", theoperator is "In", and thevalues array contains only "value".matchExpressions is a list of pod selector requirements. Valid operators includeIn, NotIn, Exists, and DoesNotExist. The values set must be non-empty in the case ofIn and NotIn. All of the requirements, from bothmatchLabels andmatchExpressionsare ANDed together -- they must all be satisfied in order to match.

Selecting sets of nodes

One use case for selecting over labels is to constrain the set of nodes onto whicha pod can schedule. See the documentation onnode selection for more information.

Using labels effectively

You can apply a single label to any resources, but this is not always thebest practice. There are many scenarios where multiple labels should be used todistinguish resource sets from one another.

For instance, different applications would use different values for theapp label, but amulti-tier application, such as theguestbook example,would additionally need to distinguish each tier. The frontend could carry the following labels:

labels:app:guestbooktier:frontend

while the Redis master and replica would have differenttier labels, and perhaps even anadditionalrole label:

labels:app:guestbooktier:backendrole:master

and

labels:app:guestbooktier:backendrole:replica

The labels allow for slicing and dicing the resources along any dimension specified by a label:

kubectl apply -f examples/guestbook/all-in-one/guestbook-all-in-one.yamlkubectl get pods -Lapp -Ltier -Lrole

NAME                           READY  STATUS    RESTARTS   AGE   APP         TIER       ROLEguestbook-fe-4nlpb             1/1    Running   0          1m    guestbook   frontend   <none>guestbook-fe-ght6d             1/1    Running   0          1m    guestbook   frontend   <none>guestbook-fe-jpy62             1/1    Running   0          1m    guestbook   frontend   <none>guestbook-redis-master-5pg3b   1/1    Running   0          1m    guestbook   backend    masterguestbook-redis-replica-2q2yf  1/1    Running   0          1m    guestbook   backend    replicaguestbook-redis-replica-qgazl  1/1    Running   0          1m    guestbook   backend    replicamy-nginx-divi2                 1/1    Running   0          29m   nginx       <none>     <none>my-nginx-o0ef1                 1/1    Running   0          29m   nginx       <none>     <none>

kubectl get pods -lapp=guestbook,role=replica

NAME                           READY  STATUS   RESTARTS  AGEguestbook-redis-replica-2q2yf  1/1    Running  0         3mguestbook-redis-replica-qgazl  1/1    Running  0         3m

Updating labels

Sometimes you may want to relabel existing pods and other resources before creatingnew resources. This can be done withkubectl label.For example, if you want to label all your NGINX Pods as frontend tier, run:

kubectl label pods -lapp=nginxtier=fe

pod/my-nginx-2035384211-j5fhi labeledpod/my-nginx-2035384211-u2c7e labeledpod/my-nginx-2035384211-u3t6x labeled

This first filters all pods with the label "app=nginx", and then labels them with the "tier=fe".To see the pods you labeled, run:

kubectl get pods -lapp=nginx -L tier

NAME                        READY     STATUS    RESTARTS   AGE       TIERmy-nginx-2035384211-j5fhi   1/1       Running   0          23m       femy-nginx-2035384211-u2c7e   1/1       Running   0          23m       femy-nginx-2035384211-u3t6x   1/1       Running   0          23m       fe

This outputs all "app=nginx" pods, with an additional label column of pods' tier(specified with-L or--label-columns).

For more information, please seekubectl label.

What's next

• Learn how toadd a label to a node
• FindWell-known labels, Annotations and Taints
• SeeRecommended labels
• Enforce Pod Security Standards with Namespace Labels
• Read a blog onWriting a Controller for Pod Labels