kubectl-label

Label a pod

$ kubectl label [[po|pods]] [pod_name] [key]=[value]

$ kubectl label [[po|pods]] [pod_name] [key]=[value] --overwrite

$ kubectl label [[po|pods]] [key]=[value] --all

$ kubectl label [[-f|--filename]] [pod_definition_file] [key]=[value]

$ kubectl label [[po|pods]] [pod_name] [key]-

kubectl label [TYPE NAME | -f FILENAME] KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--dry-run=client|server|none] [--resource-version=string]

-f, --filename []
    Filename, directory, or URL to file identifying the resource to update

--overwrite (bool, default=false)
    If true, existing labels may be overwritten

--resource-version (string)
    Update only if resource version matches; prevents concurrent modifications

--dry-run (client|server|none)
    Preview changes without applying (client simulates locally, server validates on API)

-l, --selector (string)
    Selector (label query) to filter resources; supports '=', '==', '!=', 'in', 'notin', 'ismobile', 'exists'

-L, --local (bool)
    List labels locally without querying server (requires --dry-run=client)

The kubectl label command updates or adds labels to Kubernetes resources such as pods, services, deployments, and more. Labels are key-value pairs that serve as identifying metadata for selecting and organizing objects. They enable powerful querying and operations via label selectors.

This command targets a specific resource by name and type, or multiple resources via selectors. It supports overwriting existing labels with the --overwrite flag. For instance, label a pod: kubectl label pod mypod app=v1. Bulk updates use selectors: kubectl label pods -l env=test version=2.0 --overwrite.

Labels must conform to DNS subdomain rules: keys up to 63 characters, values up to 63. Prefixes like app.kubernetes.io/ are recommended for organization. Changes are immediate and atomic per resource. Use --dry-run to preview without applying. Integrates with Kubernetes RBAC; requires update permissions on the resource.

Ideal for CI/CD pipelines, rolling updates, and node affinity rules. Does not delete labels; use kubectl label pod mypod key- to remove.

Labels cannot exceed 63 chars per key/value; no deletions without trailing '-'; requires 'update' RBAC permission; concurrent edits may fail without --resource-version.

kubectl label deployment/mydep version=1.2
kubectl label pods --all app=frontend --overwrite
kubectl label node/mynode disktype=ssd -l kubernetes.io/role=node

Use for bulk ops: -l app=nginx,env=prod or -l 'env in (dev,test),tier!=frontend'. Key for Deployments, Services, HPA.

Introduced in Kubernetes v1.0 (2014) as part of core kubectl. Enhanced with --overwrite in v1.5, label selectors refined over releases. Actively maintained by CNCF Kubernetes project.

kubectl annotate(1), kubectl patch(1), kubectl get(1), kubectl delete(1)