kubectl-annotate

Annotate a pod

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

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

$ kubectl annotate [[po|pods]] [key]=[value] [[-l|--selector]] [label_key]=[label_value]

$ kubectl annotate [[po|pods]] [pod_name] --list

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

kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VALUE_1 ... KEY_N=VALUE_N [--overwrite] [--all] [--selector=SELECTOR] [--resource-version=version] [--dry-run[=SERVER|CLIENT|NONE]] [...common-kubectl-options]

TYPE NAME | TYPE/NAME
    Specifies the resource type (e.g., pod, deployment) and its name. This is the most common way to target a single resource.

-f FILENAME
    Specifies a file containing the resource definition. This allows annotating resources defined in a local YAML or JSON file.

KEY=VALUE
    One or more key-value pairs representing the annotations to be added or updated. Keys and values must adhere to Kubernetes annotation rules.

KEY-
    Removes the annotation with the specified key. To remove multiple annotations, list each key followed by a hyphen.

--all
    If true, annotate all resources of the specified TYPE in the current namespace. For example, kubectl annotate deployments --all my-annotation=value.

--dry-run[=SERVER|CLIENT|NONE]
    If true, only print the object that would be sent, without sending it. Useful for validating changes before applying them.

--field-selector=SELECTOR
    Selects resources by their field values. Useful for filtering specific resources based on properties other than labels (e.g., --field-selector status.phase=Running).

--overwrite
    If true, allow annotations to be updated or overwritten if they already exist on the resource. Without this, attempting to modify an existing annotation will result in an error.

--resource-version=version
    Specifies a resource version for optimistic concurrency control. If set, the operation will only succeed if the resource's current version matches the provided version.

--selector=SELECTOR, -l SELECTOR
    Selects resources by labels. This allows applying annotations to multiple resources that share specific labels. Example: kubectl annotate pods -l app=myapp my-annotation=value.

--timeout=duration
    The length of time to wait before giving up on a single server request (e.g., 5s, 2m, 1h).

The `kubectl annotate` command allows users to manage annotations on Kubernetes API objects. Annotations are key-value pairs used to attach arbitrary non-identifying metadata to objects. While labels are used for identifying and selecting groups of objects, annotations are designed for storing larger, non-queryable information, such as build information, release details, configuration management, or debugging data.

This command provides a straightforward way to add new annotations, modify existing ones (using the --overwrite flag), or remove them from resources like pods, services, deployments, and more. Annotations are crucial for tools and libraries that need to store additional context about an object without affecting its operational behavior or selection criteria. They facilitate automated workflows and provide human-readable context for administrators and developers.

• Labels vs. Annotations:
  Annotations are designed for non-identifying metadata, while labels are for identifying attributes that can be queried and selected. Do not use annotations for grouping or selecting resources; use labels for that purpose.
• Size Limits:
  Kubernetes annotations have size limits, typically around 256KB per object. Storing excessively large amounts of data can impact performance and API server stability.
• Permissions:
  Users need appropriate permissions (e.g., update on the target resource type) to modify annotations.
• Value Syntax:
  Annotation values are strings. Complex data structures must be serialized (e.g., as a JSON string) before being used as an annotation value.

To remove an annotation, append a hyphen to the annotation key without a value. For example, kubectl annotate pod my-pod my-old-annotation-. This is an efficient way to clean up unwanted metadata.

Annotations are widely used by tools for release management (e.g., Helm stores release metadata), build systems (e.g., Git commit IDs, build numbers), and debugging (e.g., last applied configuration, debug flags, or configuration management details).

• Use descriptive keys, often prefixed with a domain (e.g., mycompany.com/build-id) to avoid conflicts.
• Avoid storing sensitive information directly in annotations; prefer references to secrets.
• Keep annotation values relatively small to prevent performance issues and ensure manageability.

The concept of annotations was introduced early in Kubernetes' development to provide a flexible mechanism for attaching arbitrary, non-identifying metadata to API objects, distinct from labels used for selection. The `kubectl annotate` command has been a core part of the `kubectl` CLI since its inception, offering a direct and programmatic way to manage this metadata. It evolved as Kubernetes matured, incorporating features like --overwrite, --all, and --dry-run to enhance usability and safety in managing resource annotations across various versions.

kubectl label(1), kubectl describe(1), kubectl edit(1), kubectl get(1), kubectl apply(1)