Helm Chart Dependencies & Subcharts

TL;DR

Declare dependencies in Chart.yaml, run helm dependency update, and override subchart values with the subchart name as prefix. Umbrella charts bundle multiple subcharts into one release — common for platform add-ons and Bitnami stacks.

Subchart vs Umbrella

Pattern	What it is	Example
Subchart	Dependency bundled inside a parent chart	App chart depends on `postgresql`
Umbrella chart	Parent with no templates — only dependencies	`platform/` bundles ingress + cert-manager + monitoring
Third-party chart	Upstream chart installed directly or as dependency	Bitnami nginx, prometheus-community/kube-prometheus-stack

Declare Dependencies

Declare chart dependencies in the parent chart when your app needs a packaged subcomponent such as PostgreSQL, Redis, or a shared library chart. Pin versions so upgrades are intentional and reviewable.

yaml Chart.yaml

apiVersion: v2
name: web-api
version: 2.0.0

dependencies:
  - name: postgresql
    version: "15.5.38"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled       # Skip when false.

  - name: redis
    version: "19.x.x"
    repository: https://charts.bitnami.com/bitnami
    tags:
      - cache                           # Enable via tags.cache=true.

  - name: common
    version: "1.0.0"
    repository: file://../common        # Local path dependency.

Dependency Commands

Use these commands to download, vendor, inspect, and update subcharts. Run them before rendering or packaging so Helm has the exact dependency versions listed in the lock file.

bash deps.sh

helm dependency update ./web-api    # Download deps → charts/ dir; update Chart.lock.
helm dependency build ./web-api     # Rebuild from Chart.lock (CI — reproducible).
helm dependency list ./web-api      # Show declared vs vendored versions.

# Explore third-party charts before adopting.
helm repo add bitnami https://charts.bitnami.com/bitnami
helm search repo postgresql
helm show values bitnami/postgresql > postgresql-defaults.yaml

Override Subchart Values

Subchart values are nested under the subchart's name in the parent's values.yaml.

yaml values.yaml

postgresql:
  enabled: true
  auth:
    username: webapi
    database: webapi
    existingSecret: web-api-db-secret   # Prefer existing Secret over inline password.

redis:
  enabled: false

tags:
  cache: false                          # Disables all charts tagged "cache".

global:
  storageClass: gp3                     # Passed to subcharts that read .Values.global.

Umbrella Chart Example

An umbrella chart groups multiple charts under one platform release. Use it carefully for shared add-ons, and keep ownership clear so teams know whether to change the umbrella or the child chart.

text platform-tree.txt

platform/                    # Umbrella — no templates/, only dependencies.
  Chart.yaml
  values.yaml
  values-prod.yaml
  charts/                    # Populated by helm dependency update.
    ingress-nginx-4.x.x.tgz
    cert-manager-v1.x.x.tgz
    kube-prometheus-stack-61.x.x.tgz

This deploy command installs the umbrella chart with production values. Use it after dependency build/update so all child charts are present and pinned.

bash umbrella-deploy.sh

helm dependency update ./platform
helm upgrade --install platform ./platform -n platform \
  -f platform/values-prod.yaml \
  --wait --timeout 15m

Upgrading Upstream Charts

Use this workflow when a third-party chart version changes. Render the old and new output with your values before applying, because upstream defaults and templates can change behavior even when your values file did not.

bash upgrade-upstream.sh

# 1. Read upstream changelog for breaking values changes.
helm show chart bitnami/postgresql --version 15.5.38

# 2. Bump version in Chart.yaml, rebuild deps.
helm dependency update ./web-api

# 3. Diff rendered output before applying.
helm template web-api ./web-api -f values-prod.yaml > /tmp/new.yaml
# Compare with previous render or live manifest.

helm diff upgrade web-api ./web-api -n app -f values-prod.yaml

Gotchas

!Commit Chart.lock to Git — it pins exact dependency versions for reproducible builds.
!Subchart values use the dependency name, not the chart's internal name if they differ (check alias).
!Large umbrella charts can exceed the Kubernetes request size limit — use helm template | kubectl apply or server-side apply if needed.
!Bitnami and other upstream charts change default values between major versions — always read the changelog.
!Run helm dependency build in CI, not update, to avoid pulling unexpected new versions.