7.17 Kubernetes Annotation Usage

Kubernetes Annotation Usage is the concrete, ecosystem-wide catalog of specific, well-known annotation keys that particular controllers, admission webhooks, and tools actually recognize and act upon, illustrating in practical terms how the abstract annotation mechanism is put to work by real, widely deployed components across a typical cluster.

kubectl's Own Annotations

last-applied-configuration

The kubectl.kubernetes.io/last-applied-configuration annotation, set automatically by client-side kubectl apply, stores a serialized copy of the most recently applied manifest, which kubectl reads back on subsequent applies to compute its three-way merge, a foundational example of a tool using an annotation purely for its own internal bookkeeping.

Ingress Controller Annotations

Vendor-Specific Behavior Configuration

Because the core Ingress resource's schema is deliberately minimal, ingress controllers such as ingress-nginx rely heavily on annotations, prefixed with their own controller-specific domain such as nginx.ingress.kubernetes.io, to configure behavior the base Ingress spec does not natively support, including request timeout values, rewrite rules, and rate limiting.

Controller Class Selection

The kubernetes.io/ingress.class annotation, largely superseded by the newer ingressClassName field but still encountered in older manifests, historically determined which ingress controller among several installed in a cluster should handle a given Ingress object.

cert-manager Annotations

Automated Certificate Issuance Triggers

cert-manager watches for annotations such as cert-manager.io/cluster-issuer on Ingress objects, using their presence to automatically provision a TLS certificate for the Ingress's hosts through the referenced issuer, turning a simple annotation into the trigger for an entire automated certificate lifecycle workflow.

Prometheus Scraping Annotations

Signaling Metrics Endpoints

The de facto convention annotations prometheus.io/scrape, prometheus.io/port, and prometheus.io/path, while not defined by Kubernetes itself, are widely recognized by Prometheus service discovery configurations as a signal that a given Pod exposes metrics and where to find them, illustrating how community convention can establish annotation meaning without any formal Kubernetes specification.

Admission and Policy Annotations

Pod Security Standard Enforcement

The pod-security.kubernetes.io/enforce annotation, applied at the namespace level, configures which Pod Security Standard level the built-in Pod Security admission controller enforces for Pods created within that namespace, an annotation directly interpreted by a core Kubernetes admission mechanism rather than a third-party tool.

Audit and Warning Levels

Related annotations, pod-security.kubernetes.io/audit and pod-security.kubernetes.io/warn, configure additional enforcement modes that record violations or surface warnings without outright blocking non-compliant Pods, giving operators a gradual rollout path before switching a namespace to full enforcement.

Deployment Rollout Annotations

Change Cause Tracking

The kubernetes.io/change-cause annotation, historically set by kubectl when using rollout history tracking, records a human-readable description of why a particular Deployment revision was created, surfaced later through kubectl rollout history to give operators context on past changes.

Autoscaling and Resource Management Annotations

Vertical Pod Autoscaler Hints

Some autoscaling tooling reads specific annotations to receive hints or overrides beyond what a resource's core spec fields express, such as indicating that a particular container within a Pod should be excluded from automatic resource recommendation adjustments.

Why This Catalog Matters in Practice

Recognizing Annotations as Live Configuration

Because so much real, functioning behavior in a production cluster is driven by annotations rather than core spec fields, recognizing and understanding a manifest's annotations is often just as important as understanding its spec when diagnosing why a particular Ingress, certificate, or scraping target is behaving the way it is.