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 [options] (POD|NODE|SERVICE|...) NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]

--field-manager string
    Name of the manager used to create or update the annotation record

--overwrite
    Overwrite existing annotation values if present

--remove stringArray
    Remove specified annotations (repeatable flag)

--resource-version string
    Update only if resource version matches (optimistic concurrency)

-f, --filename []string
    Identify resource with filename, directory, or URL

-l, --selector string
    Selector to operate on multiple resources

--namespace string
    Namespace for the resource

--dry-run=server|client|none
    Dry run without sending to server

The kubectl annotate command adds, updates, or removes annotations on Kubernetes resources such as pods, nodes, services, deployments, and more. Annotations are non-identifying metadata stored as key-value pairs in the form key=value, distinct from labels which are used for selection and organization. Unlike labels, annotations do not affect Kubernetes object behavior but serve purposes like storing build versions, contact info, or extended descriptions for tools and users.

Usage involves specifying the resource type and name followed by one or more KEY=VALUE pairs. By default, it fails if the annotation exists unless --overwrite is used. To remove annotations, use --remove. It supports input from files via -f and respects namespaces. This command is essential for attaching supplementary data without altering resource state.

Annotations have size limits: keys ≤ 63 chars, values ≤ 256 chars, total ≤ 1MB per object. Not indexed for queries like labels. Use --local with --dry-run=client for offline validation.

Add annotation: kubectl annotate pod/nginx app.version=v1.2.3
Overwrite: kubectl annotate --overwrite pod/nginx contact=admin@org.com
Remove: kubectl annotate --remove pod/nginx description
Multiple: kubectl annotate service/web desc='Frontend' repo='github.com'

Supports stdin: echo 'key=value' | kubectl annotate -f -
JSON/YAML: kubectl annotate -f pod.yaml key=value

Introduced in Kubernetes v1.0 (2014) as part of core kubectl. Evolved with Kubernetes API changes; --remove and --field-manager added in later versions for better record tracking and Applied status.

kubectl(1), kubectl label(1), kubectl patch(1), kubectl describe(1)