Annotations in Kubernetes are metadata attached to objects like Pods, Services, and Deployments to store additional, non-identifying information. They are key-value pairs that can hold large amounts of data, such as JSON blobs. Unlike labels, annotations are not used to identify and select objects.

Differences Between Labels and Annotations

  • Labels:

    • Used for identifying and selecting objects.
    • Often used in selectors and queries.
    • Must conform to certain size and format restrictions.
  • Annotations:

    • Store additional, arbitrary data.
    • Not used in queries or selectors.
    • Can hold larger and more complex data.
Example: Labels vs Annotations


    app: my-app
    environment: production


  annotations: "some value"

Use Cases for Annotations

  • Documentation: Store information about who last modified the object, why it exists, etc.
  • Tool Configuration: Configure and enable behavior for tools like monitoring dashboards or debugging utilities.
  • Field Management: Attach fields managed by declarative configurations, helm charts, etc.
Example: Annotations for Documentation
    createdBy: "John Doe"
    reasonForExistence: "Microservice for payments"

Best Practices and Limitations

  • Do not store sensitive data: Annotations are not designed for storing sensitive information like passwords.
  • Data Limit: Annotations and labels together should not exceed 262,144 bytes per object.
  • Readability: Store data in a way that is easily readable and understandable.
  • Immutability: Be cautious when automatically updating annotations; they should generally not change once set unless the change is meaningful.

Tools and Extensions Leveraging Annotations

  • Prometheus: For scraping metrics.
  • Istio: For traffic routing and management rules.
  • Fluentd / Fluent Bit: For log metadata.
  • Helm: To track the release status of deployments.
Example: Annotations in Prometheus
  annotations: "true" "8080"

Troubleshooting Exercise

  1. Setup: Create a pod with an annotation.

    kubectl apply -f my-pod.yaml


    apiVersion: v1
    kind: Pod
      name: my-pod
        createdBy: "John Doe"
      - name: my-container
        image: nginx
  2. Exercise: Your task is to identify why the createdBy annotation is not appearing in pod details.

    kubectl describe pod my-pod
  3. Debugging: Check if the yaml file was applied correctly.

    kubectl get pod my-pod -o yaml
  4. Solution: If the createdBy annotation is missing, ensure that the YAML indentation and key-value pair for the annotation are correct. Reapply the configuration.

    kubectl apply -f corrected-my-pod.yaml