TopolearnUmbrella charts and bundled databases are built from dependencies; their values scoping trips people up.
A chart can depend on other charts, listed in Chart.yaml under dependencies with name, version (a SemVer range like ~16.4.0), repository (an HTTP repo URL, oci://..., or file://../common), and optionally condition, tags and alias.
helm dependency updatedownloads them intocharts/and writesChart.lockwith exact versions;helm dependency buildrestores from the lock file. CommitChart.lock.- Values for a subchart go under its name (or alias) in the parent's values:
postgresql.auth.database: shop. condition: postgresql.enabledlets users switch the subchart off, for example to use a managed database in production.aliaslets you include the same chart twice under different names.
Scoping rules: a subchart sees only its own section of values, never the parent's. The exception is global: .Values.global.* is shared with every subchart. A parent can read a subchart's values, not the other way around.
Templates in a subchart can't refer to the parent's helpers, but named templates are global, which is why common library charts work.
An umbrella chart with only dependencies is a popular way to install a whole stack in one release; but one release also means one blast radius and one upgrade, so keep umbrellas small.
Example
# Chart.yaml
apiVersion: v2
name: shop
version: 1.4.0
appVersion: "1.5.0"
dependencies:
- name: postgresql
version: "~16.4.0"
repository: oci://registry.example.com/charts
condition: postgresql.enabled
# values.yaml
postgresql:
enabled: true
auth: {database: shop, username: shop}
global:
imageRegistry: registry.example.com # visible to all subcharts
# helm dependency update ./shop -> charts/postgresql-16.4.x.tgz + Chart.lockRemember
- Declare in Chart.yaml; helm dependency update; commit Chart.lock
- Configure a subchart under its name; global is shared
- condition/tags toggle subcharts on and off
Watch out for
- Expecting a subchart template to read the parent's top-level values.