In contrast to Kubernetes labels, annotations are not used to identify and select objects. The metadata in an annotation can be small or large, structured or unstructured, and can include characters not permitted by labels.

Like labels, annotations are represented as key-value pairs:

"annotations": {
  "keyA": "valueA",
  "keyB": "valueB"
}

Here are some example use-cases for annotations:

  • Storing information managed by a declarative configuration layer. Attaching these fields as annotations distinguishes them from default values set by clients or servers, and from auto-generated fields and fields set by auto-sizing or auto-scaling systems.
  • Build, release, or image information like timestamps, release IDs, git branch, PR numbers, image hashes, and registry address.
  • Pointers to logging, monitoring, analytics, or audit repositories.
  • Client library information that can be used for debugging purposes: for example, name, version, and build information.
  • User or tool/system provenance information, such as URLs of related objects from other ecosystem components.
  • Lightweight rollout tool metadata: for example, config or checkpoints.
  • Contact information of persons responsible for managing the resource.

Instead of using annotations, you could store this type of information in an external database or directory; however, external storage would make it much harder to produce shared client libraries and tools for deployment, management, and introspection.

Did this answer your question?