Labels and Selectors

What are labels and selectors, and why do they matter? Labels and selectors are the standard way to group and filter resources in Kubernetes. Think of labels as small key/value metadata you attach to objects (Pods, Deployments, Services, etc.), and selectors as queries that match objects by those labels. This is the same idea as tags on blog posts, product filters in online stores, or categories for media. For example, you might want to see:

All green animals → color = green
All green birds → color = green AND class = bird

In Kubernetes you can use labels to identify the application, role, environment, owner, and more. Selectors let controllers and users filter and operate on the subset of objects that match those labels.

A split screenshot of an online course page titled "Kubernetes for the Absolute Beginners," showing a course-structure video thumbnail, tags and links on the left. On the right is a text panel describing quiz types and tasks for Docker/Kubernetes practice.

Kubernetes manages many object types, and in any non-trivial cluster you may have hundreds or thousands of objects. Labels and selectors provide a consistent, lightweight way to organize and find related objects by application, environment, or purpose. How labels are applied

Attach labels in an object’s metadata.labels field.
Labels are arbitrary key/value pairs (strings) and you can add as many as needed.
Use selectors to query those label values when listing or operating on objects.

An illustrated diagram titled "Labels and Selectors in Kubernetes" showing colored groups of shapes (circles, triangles, rectangles) organized into labeled boxes like Front-End, Back-End, Web-Servers, App-Servers, Auth, DB, Cache, Image-Processing and Video-Processing. The visual represents how different Kubernetes resources are grouped and selected using labels.

Example: Label a Pod Below is a minimal Pod manifest showing labels under metadata:

A dark-themed infographic titled "Labels" showing colorful shape icons (circles, rectangle, triangle) paired with rounded label tags that list App and Function names like App1–App5 and Front-End, Web-Servers, DB, Auth, Image-proc. The layout groups each shape with its corresponding app/function labels across the image.

apiVersion: v1
kind: Pod
metadata:
  name: simple-webapp
  labels:
    app: app1
    function: front-end
spec:
  containers:
    - name: simple-webapp
      image: simple-webapp
      ports:
        - containerPort: 8080

Select labeled objects with kubectl Use kubectl and the --selector or -l flag to filter resources:

kubectl get pods --selector app=app1
# or
kubectl get pods -l app=app1

Example output:

NAME           READY   STATUS    RESTARTS   AGE
simple-webapp  1/1     Running   0          1d

How controllers use labels and selectors Controllers (ReplicaSets, Deployments, Services, etc.) use selectors to discover which objects they should manage or route traffic to. ReplicaSet label placement A ReplicaSet manifest typically includes labels in more than one place:

metadata.labels — labels on the ReplicaSet object itself (useful for selecting ReplicaSets).
spec.template.metadata.labels — labels applied to Pods created by the ReplicaSet.
spec.selector.matchLabels (or spec.selector.matchExpressions) — defines which Pods the ReplicaSet manages and must match the pod template labels exactly.

If the selector doesn’t match the pod labels, the ReplicaSet will not manage the Pods — this mismatch is a common source of errors. Example ReplicaSet manifest:

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: simple-webapp
  labels:
    app: app1
    function: front-end
  annotations:
    buildversion: "1.34"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: app1
  template:
    metadata:
      labels:
        app: app1
        function: front-end
    spec:
      containers:
        - name: simple-webapp
          image: simple-webapp

Key points:

spec.selector.matchLabels is used by the ReplicaSet to find Pods.
The pod template labels must satisfy the selector.
Top-level metadata.labels on the ReplicaSet are separate; they let other objects or kubectl select the ReplicaSet itself.

Services and selectors Services typically include a spec.selector that matches Pod labels. The Service routes traffic to all Pods whose labels satisfy that selector. Best practices and constraints

Best practices and constraints:

Label keys and values are typically lowercase. Use qualified keys (for example: example.com/key) when necessary.
A label key optionally includes a DNS prefix and a name separated by a slash. The name (after the slash or the whole key if no prefix) must be ≤ 63 characters. If a DNS prefix is present it must be a valid DNS subdomain (≤ 253 characters).
Label values must be ≤ 63 characters and may be empty. They should start and end with an alphanumeric character and may contain dashes, underscores, or dots in between.
Use labels only for identifying and selecting objects. Use annotations for non-identifying, descriptive metadata (e.g., build info, contact details).

Annotations vs labels Annotations are similar to labels in structure but are intended for non-identifying metadata. Use annotations to record information like build versions, CI/CD data, contact info, or links to external systems. Annotations are not used for selection. Try it hands-on

Create a Pod manifest with labels and apply it: kubectl apply -f pod.yaml.
List and filter: kubectl get pods -l app=app1,function=front-end.
Create a ReplicaSet that selects those labels and observe how Pods are managed.

Resource examples and common commands

Resource	Typical label usage	Example command
Pod	Identify app, role, environment	`kubectl get pods -l app=app1`
ReplicaSet / Deployment	Use selectors to manage Pods; pod template gets labels	`kubectl describe rs simple-webapp`
Service	Selects Pods to route traffic to	`kubectl get svc -l app=app1`
Namespace / Node	Can be labeled for organization and scheduling	`kubectl label node node01 size=large`

Links and references

Kubernetes Labels and Selectors: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
Kubernetes API conventions: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/

That’s it for this lesson on labels, selectors, and annotations. Try these concepts hands-on with your cluster and combine labels with deployments, services, and selectors to model real-world environments and traffic flows.

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

Labels and Selectors

Watch Video

Practice Lab