In a Helm Chart.yaml, what does apiVersion: v2 declare, and which fields are mandatory?

## What `apiVersion` names, and what it doesn't The word `apiVersion` appears twice in a Helm chart's world and means different things each time. Inside `templates/`, an `apiVersion:` line is a Kubernetes API group and version on a rendered object. At the top of `Chart.yaml`, `apiVersion` is the version of the **chart file format itself** — the schema Helm uses to read that file. It takes a literal value, not a number: `v2` is the format Helm 3 and Helm 4 write and read, and `v1` is the older Helm 2-era format. ## What `v2` changed from `v1` The practical difference between the two formats is where a chart's dependencies live and whether the chart can declare a type. | Axis | `v1` | `v2` | |---|---|---| | Dependencies declared in | a separate `requirements.yaml` beside `Chart.yaml` | `Chart.yaml` itself, as a `dependencies` list | | `type` field | none — no notion of a chart that is not installable | present, with two legal values, `application` and `library` | That is the whole of it: `apiVersion: v2` is a statement about the metadata file's shape, and a candidate who says it selects a Kubernetes API version, or that it is somehow related to `version` or `appVersion`, has missed the layer it lives at. ## The three mandatory fields Helm requires `apiVersion`, `name` and `version`. A `Chart.yaml` missing any one of them fails to load — you get an error before anything renders, from `helm install`, `helm template` and `helm lint` alike. That is a shorter list than most people expect, because the scaffold `helm create` writes about ten fields and they all look obligatory. `description`, `appVersion`, `type`, `kubeVersion`, `home`, `sources`, `keywords`, `maintainers`, `icon`, `deprecated` and `annotations` are every one of them **optional**. ## `name`, and the ambiguity it invites `name` is the chart's name: lowercase letters, digits and dashes, and by convention identical to the directory the chart lives in — `helm lint` will complain when the two disagree, and `helm package` names the tarball from the `name` field regardless of what the directory is called, which is exactly how you end up with a `foo-1.0.0.tgz` inside a directory called `bar`. It is *not* the release name. A release name is chosen by whoever installs (`helm install tiles ./tile-server`) and reaches templates as `.Release.Name`, while the chart name reaches them as `.Chart.Name`. This matters for a chart designed to be installed more than once: a multi-tenant chart installed once per team namespace has one chart name and seventeen release names, which is why resource names in a well-written chart are derived from the release name rather than the chart name. ## `type`, and the optional fields worth knowing exist `type` has two legal values. `application` is the default and means what it sounds like: the chart renders manifests and can be installed. `library` means the chart exists to be consumed by other charts — it renders nothing of its own, and Helm refuses to install it directly, reporting that library charts are not installable. Mechanically, that refusal is the whole of what the `type` field changes; what a library chart is *for* and how you design one is a separate discussion. Four more optional fields are worth recognising, none of which affect rendering: - `kubeVersion` holds a SemVer range of Kubernetes versions the chart supports, and Helm enforces it. - `deprecated: true` is a boolean that marks a chart as no longer maintained, which chart catalogues and search use to hide it. - `annotations` is a free-form string map of chart-level metadata that Helm carries but does not act on. - `maintainers` is a list of `name`/`email`/`url` entries, and `icon` is a URL. ## Helm 4, and how this gets asked Helm 4 contains an experimental `v3` chart format, gated behind the `HELM_EXPERIMENTAL_CHART_V3` environment variable and living in an internal package. It is not something to author against: charts you publish today are `apiVersion: v2` whether the consumer runs Helm 3 or Helm 4, and the top-level command set for working with them is identical across both. If an interviewer asks what changed for chart metadata in Helm 4, the honest and correct answer is: nothing in the field set. The question usually arrives as a quick probe — "what does `v2` mean?" — followed by "and what happens if I delete `description`?" The answer to the second is *nothing*, and being confident about which fields are load-bearing versus decorative is what the question is actually measuring.