Managing Annotations

1. Adding Annotations

Annotations in Kubernetes are key-value pairs that can be attached to objects like pods, services, or deployments. They are used to store additional metadata that is not part of the core configuration but can be useful for tools and libraries.

Property	Description	Example
metadata.annotations	Map of key-value pairs to be attached as annotations.	`"annotations": { "key1": "value1", "key2": "value2" }`

Example: Adding Annotations to a Pod

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    app.kubernetes.io/name: "my-app"
    app.kubernetes.io/version: "1.0"
    description: "This is a sample pod with annotations"
spec:
  containers:
  - name: my-container
    image: nginx

Note: Annotations are not used by the Kubernetes control plane, but they can be consumed by external tools or libraries.

2. Viewing Annotations

Resource Type	Command	Notes
Pod	`kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}'`	Displays all annotations in JSON format
Deployment	`kubectl get deployment <deployment-name> -o jsonpath='{.metadata.annotations}'`	Displays all annotations in JSON format
Service	`kubectl get service <service-name> -o jsonpath='{.metadata.annotations}'`	Displays all annotations in JSON format
Namespace	`kubectl get namespace <namespace-name> -o jsonpath='{.metadata.annotations}'`	Displays all annotations in JSON format

Example: Viewing Annotations on a Pod

kubectl get pod my-pod -o jsonpath='{.metadata.annotations}'

Note: Annotations are key-value pairs stored in the metadata section of Kubernetes resources. They are used to store non-identifying information such as build metadata, release versions, or configuration details.

3. Removing Annotations

Annotation Key	Removal Method	Notes
example.com/old-key	`kubectl annotate deployment my-deployment --remove example.com/old-key`	Removes the specified annotation from the deployment resource
custom.annotation	`kubectl annotate configmap my-config --remove custom.annotation`	Removes the annotation from a configmap resource

Example: Remove annotation from a pod

kubectl annotate pod my-pod --remove example.com/old-key

Note: The --remove flag is used to remove a specific annotation key from the resource.

Warning: Removing annotations may affect monitoring or other tools that depend on them.

4. Using Annotations in YAML

Field	Description	Example
metadata.annotations	Map of key-value pairs used to store metadata about the resource	`"app.kubernetes.io/name": "myapp" "app.kubernetes.io/version": "1.0"`

Example: Pod with Annotations

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    app.kubernetes.io/name: "myapp"
    app.kubernetes.io/version: "1.0"
    kubernetes.io/created-by: "my-deployment"
spec:
  containers:
  - name: my-container
    image: nginx:latest

Note: Annotations are not used by Kubernetes core components but can be consumed by external tools or custom controllers.

5. Understanding Common Annotations

Annotation	Values	Description
kubernetes.io/ingress.class	`nginx`	Specifies the ingress class to use for routing traffic
nginx.ingress.kubernetes.io/rewrite-target	`/`	Defines the target path for URL rewrites in NGINX ingress
prometheus.io/scrape	`true`, `false`	Controls whether Prometheus should scrape metrics from this resource
app.kubernetes.io/name	`my-app`	Identifies the name of the application
app.kubernetes.io/version	`v1.2.3`	Identifies the version of the application
app.kubernetes.io/instance	`my-app-instance-1`	Identifies the instance name of the application
app.kubernetes.io/component	`frontend`	Identifies the component within the application
app.kubernetes.io/part-of	`my-app`	Identifies the overall application this component is part of
app.kubernetes.io/managed-by	`helm`	Identifies the tool managing this resource (e.g., Helm, Kustomize)
kubernetes.io/cluster-autoscaler/enable	`true`, `false`	Enables or disables cluster autoscaler for a node pool

Example: Using Annotations in a Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
  annotations:
    prometheus.io/scrape: "true"
    app.kubernetes.io/name: "my-app"
    app.kubernetes.io/version: "v1.2.3"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app

Note: Annotations are key-value pairs that can be used to store arbitrary non-identifying metadata about Kubernetes resources.

6. Using Deployment Annotations

Annotation	Value Type	Description	Example
deployment.kubernetes.io/revision	`string`	Tracks the revision of the deployment	`"1"`
kubectl.kubernetes.io/restartedAt	`timestamp`	Indicates when the deployment was restarted	`"2024-05-20T10:00:00Z"`
kubernetes.io/ingress.class	`string`	Specifies the ingress class for routing rules	`"nginx"`

Example: Adding Annotations to a Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  annotations:
    deployment.kubernetes.io/revision: "1"
    kubectl.kubernetes.io/restartedAt: "2024-05-20T10:00:00Z"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx

Note: Annotations are key-value pairs that can be used to store additional metadata about Kubernetes objects. They are not used by the Kubernetes API server for operations but can be used by tools and libraries to store or retrieve information.

7. Configuring Ingress Annotations

Annotation	Values	Description
nginx.ingress.kubernetes.io/rewrite-target	`/`	Specifies the target path for URL rewriting
nginx.ingress.kubernetes.io/ssl-redirect	`true` or `false`	Enforces HTTPS redirect for all HTTP requests
nginx.ingress.kubernetes.io/proxy-body-size	`1m`, `2g`	Sets the maximum allowed body size for proxy requests
nginx.ingress.kubernetes.io/auth-type	`basic`, `digest`	Authentication method for protected resources
nginx.ingress.kubernetes.io/cors-allow-origin	`*`, `https://example.com`	Specifies allowed origins for CORS policy
nginx.ingress.kubernetes.io/load-balance	`round_robin`, `least_conn`	Load balancing algorithm used by NGINX Ingress Controller

Example: Basic Ingress with Annotations

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

8. Using Prometheus Annotations

Annotation	Values	Description
prometheus.io/scrape	`true` or `false`	Controls whether Prometheus should scrape the target. Default is `true`.
prometheus.io/path	`/metrics` or custom path	Path to scrape metrics from. Default is `/metrics`.
prometheus.io/port	`9090` or custom port	Port to scrape metrics from. Default is `9090`.
prometheus.io/interval	Duration (e.g., `30s`)	Scrape interval for the target. Overrides default scrape interval.

Example: Annotating a Deployment for Prometheus

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/path: "/metrics"
    prometheus.io/port: "8080"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app-container
        image: my-app-image
        ports:
        - containerPort: 8080

Note: Ensure that the Prometheus instance has access to the target service and that the metrics endpoint is correctly exposed.

9. Setting Autoscaler Annotations

Annotation	Values	Description
cluster-autoscaler.kubernetes.io/safe-to-scale	`true`	Allows the cluster autoscaler to scale the node group
cluster-autoscaler.kubernetes.io/enable-dry-run	`true`	Enables dry run mode for the autoscaler
cluster-autoscaler.kubernetes.io/scale-down-unneeded-time	`10m`	Time after which a node can be scaled down if it is not needed
cluster-autoscaler.kubernetes.io/scale-down-delay-after-add	`10m`	Delay before scaling down after a new node is added

Example: Setting Annotations on a Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  annotations:
    cluster-autoscaler.kubernetes.io/safe-to-scale: "true"
    cluster-autoscaler.kubernetes.io/enable-dry-run: "true"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      annotations:
        cluster-autoscaler.kubernetes.io/scale-down-unneeded-time: "10m"
    spec:
      containers:
      - name: nginx
        image: nginx:1.19

Note: These annotations are specific to the Cluster Autoscaler and must be applied to resources that the autoscaler manages.

10. Understanding Annotation Size Limits

Property	Value	Description
annotation.size.limit	`256KiB`	Maximum size allowed for a single annotation value in Kubernetes
annotation.key.size.limit	`63KiB`	Maximum size allowed for a single annotation key in Kubernetes
total.annotations.size.limit	`256KiB`	Total size limit for all annotations on a single resource

Note: Annotations are intended for storing human-readable metadata, not large binary data or configuration files. Exceeding these limits may cause resource creation or update failures.