Annotation Patterns

Annotations attach non-identifying metadata to Kubernetes objects. Unlike labels, annotations are not used for selection or filtering -- they store supplemental information for tools, libraries, and humans.

Adding Annotations

Use kubectl annotate to add annotations to existing resources:

# Add an annotation to a deployment
kubectl annotate deployment api-server description="Main API gateway"

# Add a contact annotation
kubectl annotate service payment-svc owner="billing-team@company.com"

# Overwrite an existing annotation
kubectl annotate deployment api-server description="Updated API" --overwrite

# Remove an annotation
kubectl annotate deployment api-server description-

Annotations in YAML

Define annotations in the metadata.annotations section:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  annotations:
    kubernetes.io/change-cause: "Updated to v2.3 for performance fix"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    app.company.com/owner: "frontend-team"
    app.company.com/runbook: "https://wiki.internal/runbooks/frontend"
spec:
  replicas: 2
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - name: frontend
          image: frontend:2.3

Common Annotation Patterns

Annotation	Purpose
`kubernetes.io/change-cause`	Records why a rollout happened
`prometheus.io/scrape`	Tells Prometheus to scrape this resource
`nginx.ingress.kubernetes.io/rewrite-target`	Configures NGINX ingress behavior
`kubectl.kubernetes.io/last-applied-configuration`	Stores the last `kubectl apply` manifest

Labels vs Annotations -- When to Use Which

Use labels when you need to select, filter, or group resources. Labels drive how Services find Pods, how Deployments manage ReplicaSets, and how you query with -l.

Use annotations when you need to store metadata that is not used for selection. Annotations hold build info, contact details, tool configuration, and documentation links.

A helpful rule: if you would use the value in a -l selector, it is a label. If it is informational or consumed by a tool, it is an annotation.

Key Takeaways

Annotations store non-identifying metadata -- they cannot be used in selectors
Use kubectl annotate to add, update, or remove annotations
Common annotations configure tools like Prometheus, NGINX Ingress, and rollout history
Labels are for selection and grouping; annotations are for everything else