How do you create a Helm library chart for shared templates across teams?

Imagine a library chart as a shared toolbox in a woodworking shop. Each carpenter builds different furniture, but they all reach for the same set of precision tools: measuring tapes, squares, and clamps. Instead of every carpenter buying their own identical set, the shop provides one shared toolbox that everyone references. A Helm library chart works the same way: it holds reusable template definitions that multiple application charts import, eliminating copy-paste duplication and ensuring consistency across dozens of microservices maintained by different teams.

A library chart is declared by setting type to library in Chart.yaml instead of the default application type. This type designation tells Helm that the chart contains no installable resources and should never be deployed directly. The chart consists entirely of files in the templates directory, but unlike application charts, these files contain only named template definitions wrapped in define and end blocks. There are no standalone Kubernetes manifests. Consumer charts declare the library as a dependency in their Chart.yaml, run helm dependency update to pull it into their charts subdirectory, and then invoke the library templates using the include function. The library chart follows the same versioning semantics as any chart, allowing consuming teams to pin to a specific version and upgrade deliberately when the platform team releases a new version.

Internally, when Helm processes a chart with library dependencies, it loads the library templates into the same template namespace as the parent chart. This means a library template defined as my-library.deployment is accessible in any consuming chart via include. The template receives the calling chart's context through the dot argument, giving it access to .Values, .Release, and .Chart of the consumer, not the library. This context passing mechanism is what makes library charts powerful: a single deployment template can render correctly for payments-api, checkout-worker, or order-service because it reads the consumer's values at render time. Library templates can call other library templates, enabling composition patterns where a base labels template feeds into a deployment template that feeds into a full application stack template.

In production, platform engineering teams typically maintain a single library chart repository that codifies organizational standards. The library enforces consistent labeling conventions, security contexts, resource quotas, pod disruption budgets, anti-affinity rules, and sidecar injection across every microservice. When a company-wide policy changes, such as requiring read-only root filesystems or adding a new mandatory label, the platform team updates the library chart, bumps its version, and consuming teams adopt the change by updating their dependency version. This centralized governance model scales from ten to hundreds of microservices without requiring individual pull requests to every chart repository. CI pipelines can enforce a minimum library chart version to prevent teams from running outdated standards.

A common gotcha is forgetting that library chart templates execute in the consumer's context, which means the library cannot assume specific value paths exist. Robust library templates use the default function and conditional blocks to handle missing values gracefully rather than failing with nil pointer errors. Another mistake is creating overly opinionated library templates that force every consumer into a rigid structure. Design library templates to accept configuration through a well-documented values schema, and provide escape hatches using named blocks that consumers can override. Test library templates by maintaining a companion test application chart in the same repository that imports the library and runs helm template validation in CI to catch breaking changes before release.