Using Helm Chart Dependencies for Reproducible Releases

The problem: drifting chart versions

When a Helm chart pulls in other charts as dependencies, a simple version bump in the upstream chart can silently change what gets installed. Without a lock mechanism, two teams might end up running different versions of the same dependency, making troubleshooting hard and releases non‑repeatable.

How Helm’s dependency management works

Helm treats each chart as a package that can list other charts in its Chart.yaml under a dependencies section. Running helm dependency update resolves those entries against the configured repositories, downloads the exact chart tarballs into the charts/ directory, and writes a Chart.lock file that records the exact versions used.

Workflow: declare, lock, upgrade

1. Declare dependencies – Add a dependencies block to Chart.yaml. Example for a Redis dependency:

dependencies:
  - name: redis
    version: "12.1.3"
    repository: https://charts.bitnami.com/bitnami

1. Resolve and lock – Run the update command from the chart’s root directory:

helm dependency update

This creates/updates charts/redis-12.1.3.tgz and writes or updates Chart.lock with the exact version and checksum.

1. Commit the lock file – Add Chart.lock (and optionally the charts/ tarballs if you prefer not to rely on remote repos) to version control so every teammate gets the same bits.
2. Install or upgrade – Use helm install or helm upgrade. Helm will ignore the version in Chart.yaml and use the locked versions from Chart.lock unless you explicitly pass --dependency-update to refresh.
3. Upgrade a dependency – Change the version in Chart.yaml, run helm dependency update again, commit the new Chart.lock, then run helm upgrade --install myapp . to pick up the new version.

Worked example

Suppose you have a chart named myapp that needs Redis. The files look like this:

myapp/
├── Chart.yaml
├── values.yaml
└── templates/
    └── deployment.yaml

Chart.yaml before:

apiVersion: v2
name: myapp
version: 0.1.0
dependencies:
  - name: redis
    version: "12.1.3"
    repository: https://charts.bitnami.com/bitnami

Run:

cd myapp
helm dependency update

After the command you should see:

• charts/redis-12.1.3.tgz
• Chart.lock containing:

dependencies:
- name: redis
  version: 12.1.3
  repository: https://charts.bitnami.com/bitnami
  checksum: sha256:abcd1234…

To verify that the dependency is included, do a dry‑run:

helm install --dry-run --debug myapp .

In the output you will see the Redis templates being rendered alongside your own.

Now change the Redis version to 12.2.0 in Chart.yaml, repeat helm dependency update, commit the updated Chart.lock, and run:

helm upgrade --install myapp .

Helm will now use Redis 12.2.0.

Trade‑off and limitation
The main operational overhead is remembering to run helm dependency update after any change to Chart.yaml. If you skip this step, Helm will continue to use the cached chart versions from charts/ (or fetch fresh ones if the directory is empty), which can lead to version drift between environments. Additionally, the lock file does not protect you from breaking changes inside a dependency’s chart; it only guarantees the same version is used. You still need to test upgrades of dependencies in a staging environment.

Actionable closing

  
Always declare dependencies in Chart.yaml with explicit version ranges.
  
Run helm dependency update as part of your CI pipeline before building or publishing a chart.
  
Commit Chart.lock (and optionally the charts/ directory) to Git.
  
Use helm upgrade --install --dependency-update only when you intentionally want to refresh locked versions.
  
Verify reproducibility by checking that helm get manifest returns identical resources across clusters when the same Chart.lock is present.