Annotations in Kubernetes are a way to attach arbitrary non-identifying metadata to objects. They are key-value pairs, and unlike labels, they are not used to identify and select objects. Instead, annotations can be used to store additional information that can be useful for various purposes without affecting the behavior of Kubernetes itself.

The metadata in an annotation can be small or large, structured or unstructured, and can include characters not permitted by labels. It is possible to use labels as well as annotations in the metadata of the same object.

Annotations, like labels, are key/value maps:

"metadata": {
  "annotations": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

Key Characteristics of Annotations:

Valid annotation keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

The kubernetes.io/ and k8s.io/ prefixes are reserved for Kubernetes core components.

• Arbitrary Key-Value Pairs: Annotations are free-form key-value pairs that can be used to attach any type of metadata to Kubernetes objects.

• Not Used for Selection: Unlike labels, annotations are not used in selectors (e.g., for service selection, replication controller selection).

• No Constraints on Values: The values of annotations can be any string, including structured data formats like JSON or XML.

• Can Be Large: Annotations can store larger amounts of data compared to labels, which are typically limited to a few kilobytes.

Example of Pod manifest with annotation:

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "https://hub.docker.com/"
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

Common Use Cases for Annotations:

Metadata for External Tools:

Annotations can be used to attach information that is used by external tools or systems. For example, a monitoring system might use annotations to store configuration details for collecting metrics from a pod.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  annotations:
    monitoring.tool/config: '{"scrape_interval": "30s", "path": "/metrics"}'

Build and Deployment Information:

Annotations can be used to store build and deployment details such as the version of the application, build date, or git commit hash.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  annotations:
    build.version: "1.0.0"
    build.date: "2024-07-08T12:34:56Z"
    build.commit: "abc123def"

Debugging and Auditing:

Annotations can be used to track the source of changes, reasons for deployments, or other debugging and auditing information.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  annotations:
    lastUpdatedBy: "DevOps Team"
    updateReason: "Security patch"

Configuration and Policy Management:

Annotations can be used to pass configuration data to controllers or admission webhooks that enforce policies or modify the behavior of resources.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  annotations:
    policy.enforcer/ignore: "true"

Operational Information:

Annotations can store operational information such as priority data or custom handling instructions for specific environments.

apiVersion: v1
kind: Pod
metadata:
  name: high-priority-pod
  annotations:
    environment: "production"
    custom.scheduler/priority: "high"
spec:
  containers:
  - name: nginx
    image: nginx:1.17.4
    ports:
    - containerPort: 80

Dynamic annotation values

Keep in mind, that annotation values can be populated dynamically in CI/CD tools. In the following examples, you will see the hardcoded values. However, on practice we can generate the annotation value dynamically by using scripts, environment variables and CI/CD toolset.

For example here's .gitlab-ci.yml for GitLab CI/CD that annotates the deployment parameters by using environment variables:

stages:
  - build
  - docker
  - deploy

variables:
  APP_VERSION: "1.2.3"

build:
  stage: build
  script:
    - echo "Building application version $APP_VERSION"
    # Add your build commands here

docker-build:
  stage: docker
  script:
    - docker build -t myapp:$APP_VERSION .
    - docker tag myapp:$APP_VERSION myregistry/myapp:$APP_VERSION
    - docker push myregistry/myapp:$APP_VERSION

deploy:
  stage: deploy
  script:
    - export BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
    - export GIT_COMMIT=$(git rev-parse HEAD)
    - |
      cat <<EOF > deployment.yaml
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: myapp-deployment
        annotations:
          build.version: "$APP_VERSION"
          build.date: "$BUILD_DATE"
          build.commit: "$GIT_COMMIT"
          deployment.team: "devops"
          deployment.reason: "feature release"
      spec:
        replicas: 3
        selector:
          matchLabels:
            app: myapp
        template:
          metadata:
            labels:
              app: myapp
            annotations:
              monitoring.tool/config: '{"scrape_interval": "30s", "path": "/metrics"}'
          spec:
            containers:
            - name: myapp-container
              image: myregistry/myapp:$APP_VERSION
              ports:
              - containerPort: 80
      EOF
    - kubectl apply -f deployment.yaml

Managing Annotations:

Annotations can be managed using kubectl commands. For example:

• Add an annotation:

    kubectl annotate pod example-pod example.com/owner="team-a"
  

• Remove an annotation:

    kubectl annotate pod example-pod example.com/owner-
  

References:

1. Medium Blog: What are Kubernetes Annotations?

2. Kubernetes Docs: Annotations