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

Labels:

metadata:
  labels:
    app: my-app
    environment: production

Annotations:

metadata:
  annotations:
    example.com/some-annotation: "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

metadata:
  annotations:
    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

metadata:
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"

Troubleshooting Exercise

1. Setup: Create a pod with an annotation.

   kubectl apply -f my-pod.yaml
   

   my-pod.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: my-pod
     annotations:
       createdBy: "John Doe"
   spec:
     containers:
     - 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