K8s by Example: Labels & Selectors

Labels are key-value pairs attached to resources. They’re the foundation of loose coupling in Kubernetes. Services find Pods, Deployments manage ReplicaSets, and NetworkPolicies target Pods, all through label selectors.
pod-labels.yaml

Labels go in the metadata section. Use consistent naming conventions across your resources.

 
metadata:
  name: my-app
  labels:
    app.kubernetes.io/name: my-app
    app.kubernetes.io/component: api

Add version and environment labels for filtering and deployment strategies.

 
    app.kubernetes.io/version: "1.0.0"
    environment: production
recommended-labels.yaml

Use recommended labels from Kubernetes documentation for consistency. These enable tooling integration, cost allocation, and monitoring dashboards.

 
labels:
  app.kubernetes.io/name: my-app
  app.kubernetes.io/instance: my-app-prod
  app.kubernetes.io/version: "1.2.0"

Organizational labels: component, part-of, managed-by. Required for most tools: name, instance, version.

 
  app.kubernetes.io/component: frontend
  app.kubernetes.io/part-of: my-platform
  app.kubernetes.io/managed-by: helm
selector.yaml

Label selectors use AND logic. For a Pod to match, it must have ALL specified labels.

 
spec:
  selector:
    app: my-app
    tier: frontend

Pods can have extra labels. Only the selector’s labels need to match.

 
metadata:
  labels:
    app: my-app
    tier: frontend
    version: v2
match-expressions.yaml

Two selector types: matchLabels (equality) and matchExpressions (set-based). Combine them for complex selection logic.

 
selector:
  matchLabels:
    app: my-app
  matchExpressions:
    - key: environment
      operator: In
      values: [staging, production]

Operators: In (value in list), NotIn (value not in list), Exists (key exists), DoesNotExist (key missing).

 
    - key: tier
      operator: NotIn
      values: [test]
    - key: release
      operator: Exists
labels-vs-annotations.yaml

Labels are for selection and grouping (queryable). Use labels for anything you need to filter on.

 
metadata:
  labels:
    app: my-app
    environment: production

Annotations are for metadata that tools consume (not queryable). Store descriptions, owners, and tool config here.

 
  annotations:
    description: "Main API server"
    owner: "platform-team@company.com"
    prometheus.io/scrape: "true"
terminal

Use -l to filter by label. Supports equality and set-based selectors.

 
$ kubectl get pods -l app=my-app
NAME                      READY   STATUS    AGE
my-app-6d4f8b7c9-abc      1/1     Running   5m
my-app-6d4f8b7c9-xyz      1/1     Running   5m
terminal

Set-based selectors use in, notin, and != for complex filtering.

 
$ kubectl get pods -l 'environment in (staging, production)'
NAME                      READY   STATUS    AGE
api-staging-abc           1/1     Running   10m
api-prod-xyz              1/1     Running   2h
terminal

Use -L to show label values as columns in the output.

 
$ kubectl get pods -L app,environment
NAME       READY   STATUS    APP      ENVIRONMENT
my-app-1   1/1     Running   my-app   production
my-app-2   1/1     Running   my-app   staging
terminal

Add or modify labels with kubectl label. Use - suffix to remove a label.

 
$ kubectl label pods my-pod env=prod
pod/my-pod labeled

$ kubectl label pods my-pod env-
pod/my-pod unlabeled
terminal

Warning: changing labels on running Pods can break Service routing or cause Deployments to create new Pods. The Pod becomes orphaned from its Deployment.

 
$ kubectl label pod my-app-xyz app=other --overwrite
pod/my-app-xyz labeled

Index | GitHub | Use arrow keys to navigate |