Chart Dependencies

Declaring and managing sub-chart dependencies in Chart.yaml, running helm dependency update, aliasing sub-charts, and conditionally enabling them.

Overview

Composing charts

Chart dependencies let you compose a complex application from several charts. Instead of copying a PostgreSQL or Redis chart into your application, you declare it as a dependency and let Helm manage fetching and lifecycle.

The dependency workflow

Dependencies are declared in Chart.yaml under the dependencies key (requires apiVersion: v2). helm dependency update does the rest.

Chart.yaml dependencies — Name, version or range, repository
charts/ — Downloaded sub-charts as .tgz archives
Chart.lock — The exact versions resolved

> [!IMPORTANT] The lockfile is what makes builds reproducible. With a range like ">=13.0.0 [!TIP] Conditions handle optional components; aliases handle repeated components.

Key concepts

helm dependency update: Downloads all Chart.yaml dependencies into charts/ as .tgz archives and writes Chart.lock. Must be run before installing a chart with declared dependencies. Resolves version ranges to specific versions.
helm dependency build: Restores dependencies from Chart.lock without re-resolving ranges. Use in CI where reproducibility matters. Equivalent to npm ci vs npm install.
Chart.lock: Lockfile produced by helm dependency update recording exact resolved versions for all dependencies. Commit to Git for reproducible builds. Should be regenerated when dependency versions in Chart.yaml change.
condition vs tags: condition is a single dot-path to a boolean value — enables/disables one dependency. tags is a list of strings that can enable/disable groups of related dependencies together. Both support the "optional component" pattern.
Alias: The alias field on a dependency overrides the sub-chart name in the values namespace. Enables using the same chart multiple times with different configurations (e.g., primary-db and replica-db, both pointing to the PostgreSQL chart).

When to use it

Bundling a database, cache, or messaging component with an application chart for self-contained deploys
Creating an umbrella chart that composes multiple microservices for a development environment
Optional infrastructure components: include PostgreSQL as a dependency but disable it in production (use RDS instead)
Reusing library charts that provide shared named templates across a platform's chart collection

Interview questions

How do you conditionally include a sub-chart dependency based on environment?
What happens to sub-chart resources during helm upgrade and rollback?
How do you use aliasing to run the same chart twice with different configurations?
Explain the Helm object install order and why it matters for dependencies.