Managing Annotations
1. Adding Annotations
| Command | Action |
|---|
kubectl annotate pod web owner=alice@x.com | Add annotation |
kubectl annotate deploy web kubernetes.io/change-cause="v1.4.2" | Track rollout cause |
kubectl annotate pod web key=val --overwrite | Update |
2. Viewing Annotations
kubectl get pod web -o jsonpath='{.metadata.annotations}'
kubectl describe pod web | grep -A1 Annotations
| Tool | Use |
|---|
describe | Human-readable |
jsonpath | Script/extract |
yq '.metadata.annotations' | Manipulate YAML |
3. Removing Annotations
kubectl annotate pod web owner-
| Syntax | Effect |
|---|
key- | Remove annotation |
4. Using Annotations in YAML
metadata:
annotations:
description: "Public web frontend"
deploy.timestamp: "2026-05-21T10:00Z"
contact: "team-web@example.com"
| Difference vs Labels | Annotation |
|---|
| Selectable | No |
| Size | Up to 256 KiB total per object |
| Content | Arbitrary strings, JSON, binary (b64) |
5. Understanding Common Annotations
| Annotation | Use |
|---|
kubectl.kubernetes.io/last-applied-configuration | Set by kubectl apply |
kubernetes.io/change-cause | Description in rollout history |
deployment.kubernetes.io/revision | Auto-incremented revision |
scheduler.alpha.kubernetes.io/... | Scheduler-specific hints |
6. Using Deployment Annotations
| Annotation | Effect |
|---|
kubernetes.io/change-cause | Recorded per revision |
deployment.kubernetes.io/revision-history-limit | Equivalent of spec field |
field.cattle.io/... | Rancher-specific |
7. Configuring Ingress Annotations
| Controller | Common Annotation |
|---|
| NGINX | nginx.ingress.kubernetes.io/rewrite-target: /$1 |
| NGINX | nginx.ingress.kubernetes.io/proxy-body-size: 50m |
| ALB (AWS) | alb.ingress.kubernetes.io/scheme: internet-facing |
| cert-manager | cert-manager.io/cluster-issuer: letsencrypt |
| Traefik | traefik.ingress.kubernetes.io/router.middlewares: ns-redirect@kubernetescrd |
8. Using Prometheus Annotations
metadata:
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
prometheus.io/scheme: "http"
| Annotation | Effect |
|---|
prometheus.io/scrape | Enable scraping |
prometheus.io/port | Metrics port |
prometheus.io/path | Metrics path |
9. Setting Autoscaler Annotations
| Annotation | Effect |
|---|
cluster-autoscaler.kubernetes.io/safe-to-evict: "true" | Allow CA to evict pod |
cluster-autoscaler.kubernetes.io/safe-to-evict: "false" | Pin pod to node |
karpenter.sh/do-not-disrupt: "true" | Karpenter equivalent |
10. Understanding Annotation Size Limits
| Limit | Value |
|---|
| Total per object | 256 KiB (all annotations combined) |
| Key | Same as labels (≤253 prefix + ≤63 name) |
| Value | No per-key limit (subject to total) |
Warning: etcd performance suffers with large objects; keep annotations small.