Using Helm Chart Dependencies with Chart.yaml and Chart.lock for Reproducible Installs

Get reproducible Helm installs by locking chart dependencies

Declare each subchart in Chart.yaml, let Helm resolve exact versions into Chart.lock, and run helm dependency build to copy the subcharts into the charts/ directory before you package or install the parent chart.

Worked example

1. Create a parent chart myapp with a Chart.yaml that lists a dependency:

# myapp/Chart.yaml
apiVersion: v2
name: myapp
version: 0.1.0
dependencies:
  - name: mysql
    version: "1.6.0"
    repository: https://charts.bitnami.com/bitnami
    alias: db

1. Initialize the lock file and download the subchart:

# run from the chart root
helm dependency build

After the command finishes, Chart.lock contains the pinned version and a charts/mysql-1.6.0.tgz file appears.

# myapp/Chart.lock (generated)
dependencies:
  - name: mysql
    version: 1.6.0
    repository: https://charts.bitnami.com/bitnami
    condition: mysql.enabled
    tags:
      - database
    alias: db
    # ... checksum omitted

1. Package or install the parent chart, telling Helm to update dependencies:

helm install myapp ./myapp --dependency-update

Helm uses the locked version, so every installation gets the same MySQL chart unless you intentionally regenerate the lock.

Limits and common mistakes

• Stale lock file: Committing Chart.lock reproduces installs but delays receiving upstream patches until you run helm dependency update.
• Private repositories: The build step fails if the dependency registry requires credentials that Helm cannot find. Configure helm registry login or add username/password fields in Chart.yaml before running helm dependency build.
• import‑values changes: Between Helm 3.0 and 3.12 the way lists are merged changed. After upgrading Helm, test that values copied with import-values appear as expected.
• Alias does not isolate resources: Using alias lets you include the same subchart multiple times, but all instances render with the original chart’s template names; Kubernetes resources may clash unless the subchart itself uses the alias to scope names.

How to verify the setup

1. Run helm dependency list in the chart root; each dependency should show OK or missing matching what is in Chart.yaml.
2. After helm dependency build, inspect charts/ to confirm the expected *.tgz files are present.
3. Open Chart.lock and check that the version and repository fields for each entry exactly match the resolved versions you expect.
4. Render templates with dependency updates and grep for a resource from the subchart, e.g.:
   helm template myapp ./myapp --dependency-update | grep -A2 "kind: Service"
   If the MySQL service appears, values were applied correctly.