kubectl label

When to Use kubectl label

kubectl label adds, modifies, or removes labels on Kubernetes resources. Labels are the primary mechanism for organizing and selecting resources. They drive Service routing, Deployment pod matching, network policies, and node scheduling.

Adding Labels

# Label a pod
kubectl label pod my-pod app=nginx

# Label a node for scheduling
kubectl label node worker-1 disktype=ssd

# Label a namespace
kubectl label namespace staging team=backend

# Multiple labels at once
kubectl label pod my-pod app=nginx tier=frontend version=v1

Removing Labels

Append a minus sign (-) to the key to remove a label:

# Remove the "environment" label
kubectl label pod my-pod environment-

# Remove from a node
kubectl label node worker-1 disktype-

Overwriting Existing Labels

By default, relabeling an existing key fails. Use --overwrite:

# This fails if "environment" already exists
kubectl label pod my-pod environment=staging
# error: 'environment' already has a value (production)

# This succeeds
kubectl label pod my-pod environment=staging --overwrite

Bulk Labeling

Label multiple resources at once:

# All pods in a namespace
kubectl label pods --all environment=staging -n staging

# Pods matching a selector
kubectl label pods -l app=nginx tier=frontend

# All nodes
kubectl label nodes --all monitoring=enabled

Node Labels for Scheduling

Labels on nodes control pod placement via nodeSelector and node affinity:

# Add a label for SSD nodes
kubectl label node worker-1 disktype=ssd
kubectl label node worker-2 disktype=hdd

# Pod using nodeSelector
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: ssd-pod
spec:
  nodeSelector:
    disktype: ssd
  containers:
  - name: app
    image: nginx
EOF

Labels and Services

Services use label selectors to route traffic. Changing pod labels can have immediate effects:

# A service selecting app=nginx
kubectl get service my-service -o jsonpath='{.spec.selector}'
# {"app":"nginx"}

# If you remove the label from a pod, it drops out of the service
kubectl label pod my-pod app-
# The pod no longer receives traffic from the service

# This is useful for debugging — remove a pod from service traffic
# while keeping it running for investigation
kubectl label pod failing-pod app-

Label Conventions

Kubernetes recommends these standard labels:

| Label | Example | Purpose | |-------|---------|---------| | app.kubernetes.io/name | nginx | Application name | | app.kubernetes.io/version | 1.19.0 | Application version | | app.kubernetes.io/component | frontend | Component within the app | | app.kubernetes.io/part-of | my-platform | Higher-level application | | app.kubernetes.io/managed-by | helm | Tool managing the resource |

Label Syntax Rules

Labels have specific format requirements:

• Keys: Optional prefix (DNS subdomain, max 253 chars) + / + name (max 63 chars). Name must start and end with alphanumeric.
• Values: Max 63 characters. Must start and end with alphanumeric. Can include -, _, ..

# Valid labels
kubectl label pod my-pod app.kubernetes.io/name=nginx
kubectl label pod my-pod version=v1.2.3
kubectl label pod my-pod my-label=value_with-special.chars

# Invalid (will fail)
kubectl label pod my-pod "invalid label=spaces not allowed"

Using Labels with get and delete

Labels work with selector flags across many commands:

# List pods with specific labels
kubectl get pods -l app=nginx,tier=frontend

# Delete pods by label
kubectl delete pods -l environment=test

# Describe all services for an app
kubectl describe svc -l app=my-app

Canary Deployment Pattern

Labels enable canary deployments by adding new pods to an existing service:

# Existing pods serve traffic
kubectl get pods -l app=my-app,version=v1

# Deploy canary with same app label but different version
kubectl label pod canary-pod app=my-app version=v2

# The service (selecting app=my-app) now routes to both v1 and v2
# Remove canary from traffic if issues arise
kubectl label pod canary-pod app-

This pattern demonstrates why understanding labels is critical for production operations and a frequent topic in Kubernetes interviews.