An annotation is a key-value metadata attribute attached to a Kubernetes object. Unlike a label, it stores non-identifying information and cannot be used to filter objects. Annotation values can be much longer and may contain any character. section 7.5 section 7.5.1
Use annotations to attach context or configure components:
- Record descriptions, creator and contact details, repository URLs, commit hashes, build timestamps, or similar application metadata. section 7.5.1
- Let kubectl and controllers store information that does not belong in the object schema. section 7.5.1
- Configure an implementation-specific feature, such as cookie-based session affinity in an Nginx Ingress. section 12.4.1
Adding annotations with kubectl and YAML
Add an annotation to an existing Pod with `kubectl annotate pod kiada-front-end created-by='Marko Luksa <marko.luksa@xyz.com>'`. For declarative configuration, place annotations under `metadata.annotations` in the manifest. Quote values such as `123`, `true`, or `yes` when YAML might interpret them as non-strings. section 7.5.2
Listing 7.7 Annotations in an object manifest
apiVersion: v1
kind: Pod
metadata:
name: pod-with-annotations
annotations:
created-by: Marko Luksa <marko.luksa@xyz.com> #1
contact-phone: +1 234 567 890 #2
managed: 'yes' #3
revision: '3' #4
spec:
...
Shows annotations in a Pod manifest, including contact information and quoted scalar values. section 7.5.2
Inspect annotations with `kubectl describe` or by reading the object's YAML or JSON definition. The general `kubectl get` listing does not provide an option to display them directly. section 7.5.3
Listing 12.9 Using annotations to configure session affinity in an Nginx ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: kiada
annotations:
nginx.ingress.kubernetes.io/affinity: cookie #1
nginx.ingress.kubernetes.io/session-cookie-name: SESSION_COOKIE #2
spec:
...
Demonstrates controller-specific annotations configuring cookie affinity and the session-cookie name on an Nginx Ingress. section 12.4.1
