Kubernetes labels and selectors explained (with examples)

Labels are key-value pairs attached to Kubernetes objects. Selectors use those labels to identify and group resources. Together they are the mechanism that connects Deployments to pods, Services to pods, and NetworkPolicies to pods. Understanding labels and selectors is fundamental to understanding how Kubernetes objects relate to each other.

Label syntax quick reference

Adding labels to a pod

Labels are defined in the metadata section of any Kubernetes object. You can also add them to existing objects imperatively.

Add a label to an existing pod:

1kubectl label pod nginx demo=true

View all pods with their labels:

1kubectl get pods --show-labels

Expected output:

1NAME    READY   STATUS    RESTARTS   AGE   LABELS
2nginx   1/1     Running   0          5m    demo=true
3

Filter pods by a specific label:

1kubectl get pods -l app=nginx

Equality-based vs set-based selectors

There are two types of selectors in Kubernetes.

Equality-based selectors match exact values using = or !=:

1app=nginx
2environment!=production

Set-based selectors support richer expressions using in, notin, and exists:

1app in (nginx, apache)
2environment notin (production)
3tier exists

Deployments and Services use equality-based selectors. Newer resources like Jobs and DaemonSets support both. If both matchLabels (equality-based) and matchExpressions (set-based) are specified, both must be true.

Common use cases

Deployments selecting pods

A Deployment uses selector.matchLabels to identify which pods it manages. Every pod created by the Deployment automatically gets the labels defined in the template.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: nginx-deployment
5spec:
6  replicas: 3
7  selector:
8    matchLabels:
9      app: nginx
10  template:
11    metadata:
12      labels:
13        app: nginx
14    spec:
15      containers:
16      - name: nginx
17        image: nginx:1.25
18        ports:
19        - containerPort: 80

Services routing traffic to pods

A Service uses selector to find the pods it should route traffic to. Any pod with matching labels becomes an endpoint for the service.

1apiVersion: v1
2kind: Service
3metadata:
4  name: nginx-service
5spec:
6  selector:
7    app: nginx
8  ports:
9  - protocol: TCP
10    port: 80
11    targetPort: 80

NetworkPolicies targeting pods

A NetworkPolicy uses podSelector to define which pods the policy applies to.

1apiVersion: networking.k8s.io/v1
2kind: NetworkPolicy
3metadata:
4  name: allow-nginx
5spec:
6  podSelector:
7    matchLabels:
8      app: nginx
9  policyTypes:
10  - Ingress

Other common uses

• Node affinity: labels on nodes allow pods to express scheduling preferences, for example requiring a pod to run only on nodes labelled disktype=ssd
• Canary deployments: label pods with version=canary and route a percentage of traffic to them via a separate Service selector
• Monitoring: Prometheus uses label selectors to decide which pods to scrape for metrics