What is the annotations map in a Helm Chart.yaml for, and who reads it?

## Chart-level metadata Helm carries but never interprets `annotations` is an optional field in `Chart.yaml`: a **map of string keys to string values**. Its purpose is to let a chart carry metadata that the `Chart.yaml` schema itself has no field for — a category, an ownership tag, a link to a changelog, a marker that some tool downstream cares about. Helm's own behaviour never depends on it. Nothing in rendering, packaging, dependency resolution, installation or upgrade branches on an annotation value. Two consumers make the field useful. ## Chart catalogues, through the repository index A classic chart repository is a directory of `.tgz` files plus an `index.yaml` that lists every chart version with its metadata. That metadata includes the `annotations` map. Because the index is a single small file, a chart catalogue or a UI can list, categorise, filter and describe hundreds of charts by fetching one document, without downloading a single tarball. This is why public chart catalogues define their own annotation key conventions — categories, changelog entries, screenshots, security or licence declarations — and why those keys are namespaced with a domain-like prefix so two consumers cannot collide. If you publish charts to a catalogue, its documented annotation keys are the interface you fill in; if you run your own index, annotations are where you put whatever your internal tooling wants to query. ## Templates, through `.Chart` The whole of `Chart.yaml` is exposed to templates as the `.Chart` object, so a chart can read its own annotations as `.Chart.Annotations`. That is occasionally useful for stamping a chart-level tag onto every rendered object, but it is a niche move: values are the right channel for anything a consumer should be able to change, and annotations are metadata about the chart artifact, not configuration. ## The three annotation surfaces, and why this gets asked "Annotation" is one of the most overloaded words in Helm, and this field is one of three distinct things it can mean. 1. **Chart-level annotations**, the field discussed here. They live in `Chart.yaml`, describe the chart, and reach the repository index. They never appear on a Kubernetes object. 2. **Annotations Helm reads off a rendered manifest.** These are the `helm.sh/` directives a chart puts on an object in `templates/` to change how Helm treats it — hook declarations, hook ordering and deletion policies, and the resource policy that keeps an object on uninstall. They only work on rendered objects; putting one in `Chart.yaml` is inert. 3. **Annotations Helm writes onto live objects.** When Helm takes ownership of a resource it stamps `meta.helm.sh/release-name` and `meta.helm.sh/release-namespace` on it, alongside a `managed-by` label. That is Helm's own bookkeeping about which release owns what — it is not derived from `Chart.yaml` and you do not author it. A candidate who can separate those three cleanly is demonstrating something more valuable than knowledge of an obscure field: they know which layer each piece of Helm metadata lives at. The commonest mistake is expecting `Chart.yaml` annotations to be copied onto rendered objects. They are not — if you want every object a chart renders to carry a common annotation, you write it into the chart's shared labels-and-annotations helper in `templates/`, not into `Chart.yaml`. ## Practical notes Values are strings, so a boolean or a number needs quoting; a nested structure has to be encoded, which is why multi-line annotation values in the wild are usually YAML documents embedded as strings. Keys should be namespaced with a prefix you own, both to avoid colliding with a catalogue's reserved keys and to make it obvious who consumes them. And because the map lands in the repository index, treat it as **public**: for a chart published to any shared index, an annotation is documentation, never a place for anything sensitive. As an interview item this is a differentiator rather than a screen. Nobody fails an interview for not knowing the field exists; the answer that scores is the one that uses the question to draw the boundary between metadata about the chart and metadata on the cluster.