kubectl-label

Label a pod

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

$ kubectl label --overwrite pod [pod_name] [key]=[value]

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

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

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

kubectl label [--overwrite] (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version] [flags]

To remove a label: kubectl label TYPE NAME KEY- [...]

Example: kubectl label pod my-pod app=nginx version=1.2 --overwrite

Example: kubectl label deployment my-app env- --all

TYPE NAME | TYPE/NAME
    The type and name of the Kubernetes resource(s) to label. Examples: pod my-pod, deployment/my-deployment, service/my-service. Multiple resources can be specified (e.g., pod pod1 pod2).

KEY=VALUE
    The label key-value pair to add or update. Keys and values must conform to Kubernetes label syntax rules. Multiple key-value pairs can be specified.

KEY-
    Appends a hyphen - to a label key to indicate that this label should be removed from the resource. Multiple label keys can be specified for removal.

--all
    If true, select all resources of the specified type in the current namespace. This cannot be used with --selector.

-f, --filename strings
    Filename, directory, or URL to files containing the resource configuration. You can specify multiple filenames or directories.

--field-selector string
    A selector to restrict the list of returned objects by field expressions. For example: --field-selector status.phase=Running.

--local
    If true, set labels in the client instead of sending the request to the Kubernetes API server. This is useful for dry-run or combining with output options.

--overwrite
    If true, allow labels to be overwritten. By default, attempting to change an existing label's value without --overwrite will result in an error.

--resource-version string
    If specified, the object will be labeled only if its resource version matches this value. This is used for optimistic concurrency control to prevent conflicting updates.

-l, --selector string
    Selector (label query) to filter on. You can specify multiple selectors separated by commas. E.g., 'app=nginx,env=prod'. This selects resources matching the specified labels.

The kubectl label command is used to add, update, or remove labels on Kubernetes objects such as Pods, Deployments, Services, and more. Labels are key/value pairs that are attached to Kubernetes objects, designed to specify identifying attributes that are meaningful and relevant to users. They can be used to organize and to select subsets of objects. For example, you might label all Pods of a particular application tier (e.g., tier=frontend) or all Pods running on a specific node (e.g., node=node1).

This command allows you to:

• Add new labels to an object.
• Change the value of an existing label (requires the --overwrite flag).
• Remove a label from an object (by appending a hyphen - to the label key).

Labels are fundamental for orchestrating resources within Kubernetes, enabling powerful selection capabilities for controllers, services, and policies.

• Label Syntax Rules: Labels must adhere to specific Kubernetes syntax rules. A label key has two parts: an optional prefix and name, separated by a slash (/). Both parts must be 63 characters or less and start/end with an alphanumeric character ([a-z0-9A-Z]), with dashes (-), underscores (_), dots (.) and alphanumerics allowed in between. The prefix, if specified, must be a DNS subdomain. The value must be 63 characters or less and similar restrictions apply.
• Case Sensitivity: Label keys and values are case-sensitive.
• --overwrite is Crucial: When modifying an existing label, the --overwrite flag is mandatory; otherwise, the command will fail to prevent accidental changes.
• Non-Existent Labels: Attempting to remove a label that does not exist on an object using KEY- will not result in an error; the command will simply complete without effect for that label.
• Impact on Controllers: Changing labels on resources can have significant impacts, as many Kubernetes controllers (like Deployments, Services, Network Policies) use labels to identify and manage related objects.

While both are key-value pairs, labels are used for identifying attributes and are intended to be queried by controllers and users (e.g., for selection, scheduling, network policies). Annotations are used for non-identifying metadata that may be useful for tools or libraries but are not directly used by Kubernetes for selection. Annotations can also be larger and contain more structured data.

Labels are extensively used for:

• Scheduling: Selecting nodes for Pods based on node labels (e.g., disktype=ssd).
• Service Discovery: Services select their backing Pods using label selectors.
• Networking: Network policies select Pods using label selectors for ingress/egress rules.
• Resource Grouping: Grouping related resources (e.g., all components of an application, different environments like dev, staging, prod).
• Monitoring: Integrating with monitoring systems that use labels to identify metrics.

The kubectl label command has been a fundamental part of the kubectl command-line tool since the early versions of Kubernetes. Its core functionality for managing resource labels has remained largely consistent, reflecting the enduring importance of labels as a primary mechanism for organizing and selecting objects within the Kubernetes ecosystem. It evolved as Kubernetes matured, providing a straightforward way to interact with the API's labeling capabilities directly from the command line, complementing declarative approaches using YAML manifests.

kubectl get(1): To view current labels on resources., kubectl describe(1): To get detailed information about a resource, including its labels., kubectl annotate(1): To manage annotations, which are similar to labels but store non-identifying metadata., kubectl apply(1): To create or update resources from files, which can include labels defined in YAML/JSON manifests.