kubectl label: Usage, Options & Common CI Errors

Add, change, or strip labels - singly or in bulk.

kubectl label mutates the labels on one or more objects. Labels drive selectors, so labelling correctly is what makes Services, Deployments, and your own kubectl get -l queries find the right pods.

What it does

kubectl label RESOURCE NAME key=value adds a label; key- (trailing dash) removes it. By default labelling an existing key fails - pass --overwrite to change it. You can target many objects at once with -l (select by existing label) or --all within a namespace.

Common usage

Terminal

kubectl label pod my-pod env=staging
kubectl label pod my-pod env=prod --overwrite
kubectl label pod my-pod env-                  # remove the label
kubectl label pods -l app=web tier=frontend    # bulk by selector

Common errors in CI

"\"env\" already has a value (staging), and --overwrite is false" is the re-run trap: the first run set the label, the retry fails because you did not pass --overwrite. Add --overwrite for idempotent scripts. "metadata.labels: Invalid value" means the value breaks the rules - label values must be ≤63 characters, alphanumeric plus -, _, ., starting and ending alphanumeric. Git branch names and image tags often violate this (slashes, leading digits via prefixes), so sanitize before labelling.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl "metadata.labels: Invalid value" - Fix Bad Label Values in CIFix kubectl "metadata.labels: Invalid value" / "metadata.annotations" errors in CI - a label value with illeg… kubectl annotate: Usage, Options & Common CI Errorskubectl annotate attaches non-identifying metadata to resources. Annotations vs labels, and the change-cause… kubectl get: Usage, Options & Common CI Errorskubectl get lists and displays Kubernetes resources. Output formats, label selectors, watch mode, and the emp…