Subcharts and Dependencies

Charts made of charts

A chart declares other charts it needs in the dependencies list of Chart.yaml, each with a name, a version range and a repository (HTTP repo or oci:// URL). helm dependency update downloads them into charts/ and writes Chart.lock with exact versions; commit the lock file and use helm dependency build in CI to reproduce it. A condition such as postgresql.enabled lets users switch a dependency off (for example, when production uses a managed database), and alias installs the same chart twice under different names. Configure a subchart from the parent by nesting values under the subchart's name; values under global are visible to the parent and every subchart as .Values.global. A subchart cannot read its parent's values. An umbrella chart is a parent whose job is mainly to install several subcharts together.

Parent and subcharts

The parent passes values down by subchart name; global values reach everyone.

Configuring a dependency from the parent

Dev uses the bundled PostgreSQL; production switches it off and points at a managed database.

# values.yaml of the parent chart
global:
  imageRegistry: registry.example.com

postgresql:            # passed to the postgresql subchart as its .Values
  enabled: true
  auth:
    database: shop
    existingSecret: shop-db-credentials

# values-prod.yaml
postgresql:
  enabled: false
externalDatabase:
  host: shop-prod.postgres.example.internal

# commands
# helm dependency update ./charts/shop-api   # writes charts/*.tgz and Chart.lock
# helm dependency build  ./charts/shop-api   # in CI: restore exactly what Chart.lock says

Do not let production data depend on a subchart toggle

A stateful subchart such as a database is convenient for dev but risky in production: an accidental helm uninstall removes it too. Many teams run production databases outside the app chart, or as a managed service.

Quick check: How does a parent chart set the `auth.database` value of a dependency called postgresql?

• In postgresql.auth.database in the parent's values
• In global.auth.database only
• By editing the subchart's files in charts/
• Subcharts cannot be configured