Library Charts

### What the field is Every Helm chart carries a `Chart.yaml`. Since the `apiVersion: v2` chart format, that file has a `type` field with exactly two legal values. `application` is the default - if you omit `type` entirely, you have an application chart - and it means the chart is a deployable unit: `helm install` renders its templates and applies the result as a release. `library` means the opposite: the chart exists only to be depended on. Helm will not install it, and it is not expected to produce a single Kubernetes object. ### Why a chart that produces nothing is useful The unit of reuse in Helm's templating is the named template - a block declared with `define` and called with `include`. Before library charts existed, the only ways to share one across charts were to copy `_helpers.tpl` into every chart repository, or to force every chart to become a subchart of one umbrella so it could see the parent's definitions. Copying means that changing a single label - adding one to the standard block every workload emits - is a hand-edit in every repository, done N times, reviewed N times, and wrong in the two places somebody missed. The umbrella means one release for everything, which is a far bigger commitment than sharing a helper. A library chart makes the helper itself the artefact. It is packaged with `helm package`, published to a chart repository or an OCI registry, versioned with semver, and pulled in by version range like any other dependency. The helper is authored once and reviewed once; adoption is then a version bump per consumer. ### What one looks like A library chart is an ordinary chart directory with `type: library` in `Chart.yaml` and a `templates/` directory whose files are all underscore-prefixed partials - `_labels.tpl`, `_names.tpl`, `_image.tpl` - each containing only `define` blocks. The underscore prefix is what guarantees the chart emits nothing: Helm treats an underscore-prefixed file as a partial rather than as a manifest source. Putting a renderable `deployment.yaml` in a library chart is the classic authoring mistake; the file has no business being there, because a library chart's whole contract is that consumers decide what objects exist. `helm create` does not scaffold a library chart. You write it by hand, or you carve one out of the `_helpers.tpl` that two of your existing charts already share. ### How an application chart uses one The consumer lists the library in its `dependencies:` block exactly as it would list a subchart, resolves it so the packaged library lands under `charts/`, and then calls the library's named templates from its own templates. At render time there is only one set of templates in play - the parent's plus everything under `charts/` - so the library's `define` blocks are simply in scope. Because none of them are attached to a file that renders, the release contains exactly the objects the application chart wrote, and not one more. A worked shape: a single-service chart with an Ingress and a HorizontalPodAutoscaler, and a separate chart for a subscription-billing cron, both depend on `platform-common` 2.4.3. Neither release gains an object from the library. Both emit an identical standard label block, because both call the same helper. ### What it is not A library chart is not a runtime import. Nothing is fetched when the release is installed: the dependency is resolved before packaging and the resolved library travels inside the consumer's tarball. Two releases installed on the same day from two consumer charts can therefore be running two different versions of the same library, and that is normal, not a bug. It is also not a shared values mechanism. Its job is templates; the interface it presents to consumers is the set of helper names it defines and the context each expects. One practical consequence of being uninstallable: you cannot smoke-test a library chart by installing it. Teams test one by keeping a thin consumer chart in the same repository and rendering that, which also gives you somewhere to assert that a helper still produces the output you promised. ### The mistakes that actually happen Three recur. A renderable manifest ends up in the library's `templates/`, usually because someone copied a file across rather than a `define` block; the fix is to move the object back to the consumer and export only the helper it needed. A helper assumes it can read its own chart's metadata, so `.Chart.Version` renders the consumer's version and a label meant to record the library version records something else entirely. And a chart is marked `library` while still being installed by a pipeline somewhere, which surfaces as a deploy job that fails the moment the type changes - worth grepping for before you flip the field on an existing chart. None of these are subtle once you hold the two rules: a library chart contributes names and nothing else, and a named template runs in the caller's world, not its own.