CKAD — Annotations

What Are Annotations?

Annotations are like labels but for non-identifying metadata. They store information that tools, libraries, or humans might need but that Kubernetes does not use for selecting or grouping objects.

Unlike labels, annotations:

• Are NOT used by selectors
• Can hold larger, unstructured data
• Have no character restrictions on values
• Are commonly used by Ingress controllers, monitoring tools, and CI/CD systems

Common Uses for Annotations

Use Case	Example Annotation
Build information	build/commit: "abc123"
CI/CD pipeline	build/pipeline: "ci-prod-456"
Team ownership	team: "platform-engineering"
Prometheus monitoring	prometheus.io/scrape: "true"
Ingress configuration	nginx.ingress.kubernetes.io/rewrite-target: /
Change tracking	kubernetes.io/change-cause: "update to v2"
Deployment tools	helm.sh/chart: "myapp-1.0.0"

Managing Annotations with kubectl

# Add an annotation
kubectl annotate pod web description="Frontend web server"

# Add multiple annotations
kubectl annotate pod web team="platform" oncall="ops-team@example.com"

# View annotations
kubectl describe pod web | grep Annotations

# View annotations in YAML
kubectl get pod web -o jsonpath='{.metadata.annotations}'

# Overwrite an existing annotation
kubectl annotate pod web description="Updated frontend server" --overwrite

# Remove an annotation (note the minus sign)
kubectl annotate pod web description-

Annotations in YAML

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
  annotations:
    build/commit: "abc123"
    build/pipeline: "ci-prod-456"
    team: "platform-engineering"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
spec:
  containers:
  - name: nginx
    image: nginx:1.27

Labels vs Annotations

Feature	Labels	Annotations
Purpose	Identify and select objects	Store non-identifying metadata
Used by selectors	Yes	No
Character limits	63 chars max for values, alphanumeric + -_.	No value length restriction
Kubernetes uses them for	Service routing, scheduling, grouping	Nothing — they are for tools and humans
Examples	app=web, env=prod	build/commit: "abc123", long JSON configs

Key difference: Labels are for selection and grouping. Annotations are for storing metadata. Labels have character restrictions (63 chars max, alphanumeric). Annotations can hold larger, unstructured data.

Real-World Annotation Patterns

Ingress Controller Configuration

Ingress controllers like NGINX rely heavily on annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/rate-limit: "10"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-svc
            port:
              number: 80

Deployment Change Tracking

Annotations power kubectl rollout history:

# Record the change cause when updating
kubectl set image deployment/web nginx=nginx:1.28 --record

# Or annotate manually
kubectl annotate deployment web kubernetes.io/change-cause="Update nginx to 1.28"

# View rollout history
kubectl rollout history deployment web
# REVISION  CHANGE-CAUSE
# 1         <none>
# 2         Update nginx to 1.28

Monitoring with Prometheus

metadata:
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"
    prometheus.io/path: "/metrics"

Exam tip: You will rarely be asked to create annotations from scratch in the CKAD exam. But you need to understand what they are, how they differ from labels, and how to add or remove them quickly.

---

Next: Understand what happens after a Pod is created with Pod Lifecycle →