Dependencies, Subcharts and Repositories

Docker & Kubernetes · Helm – The Package Manager for Kubernetes · Lesson 5 of 5

Declare dependencies in Chart.yaml and download them into charts/ with helm dependency update; values only flow from the parent chart down to subcharts.

Helm 3 declares dependencies directly in Chart.yaml (Helm 2 used requirements.yaml):

dependencies:
- name: mysql
  version: "~14.0.0"            # version ranges allowed
  repository: "@bitnami"        # alias of an added repo, or a URL / oci://
  condition: mysql.enabled      # toggle by value
  tags: [database]              # toggle by group

helm dependency update ./mychart downloads the dependencies into charts/ and writes Chart.lock. Skip it and charts/ stays empty, so the install complains about missing dependencies.

flowchart TB
  P["Parent chart mychart<br/>values: mysql.auth.database=app"] -- "overrides values" --> S["Subchart mysql"]
  G["global: { storageClass: gp3 }"] --> P
  G --> S
  S -. "cannot read parent values" .-x P

Values between parent and child

The parent chart overrides subchart values under a key named after the subchart (mysql: …).
A subchart cannot read the parent values; only global is shared.
import-values (with exports in the subchart) passes values from child up to parent.

Repositories

A repo can be a local folder, a web server or Git Pages with an index.yaml (built with helm repo index), or an OCI registry (helm push, oci://…). Extend the CLI with helm plugin install.

Command	Meaning
`helm repo update`	Refresh the index of added repos
`helm dependency update ./mychart`	Download subcharts into `charts/`
`helm push mychart-0.1.0.tgz oci://registry.example.com/charts`	Push a chart to an OCI registry

Version constraints

Constraint	Accepts
`14.2.1`	Exactly that version
`~14.2.0`	Patch updates: `>=14.2.0 <14.3.0`
`^14.2.0`	Minor and patch updates: `>=14.2.0 <15.0.0`
`>=14.0.0 <15.0.0`	An explicit range

Chart.lock records the exact versions that were resolved; commit it so every build uses the same subcharts. helm dependency build installs exactly what the lock file says, while helm dependency update re-resolves the ranges and rewrites the lock.

Using one chart twice

An alias lets you include the same subchart more than once with separate values:

dependencies:
- name: redis
  version: "^20.0.0"
  repository: oci://registry.example.com/charts
  alias: cache
- name: redis
  version: "^20.0.0"
  repository: oci://registry.example.com/charts
  alias: sessions

Values then go under cache: and sessions: in the parent's values.yaml.

Umbrella charts

An umbrella chart has few templates of its own and mostly bundles the subcharts of a whole system, so one helm install deploys everything. It is convenient for demos and tightly coupled components, but it ties their release cycles together. Many teams instead release each service separately and use Helmfile or a GitOps tool to compose them.

Global values and library charts

Use global: only for settings that truly apply everywhere, such as an image registry, a storage class, or common labels; overusing it hides where values come from. Shared template code belongs in a library chart dependency, called with include from each application chart.

Inspecting dependencies

helm dependency list ./mychart shows each dependency's status (ok, missing, wrong version). helm show values oci://registry.example.com/charts/redis --version 20.1.0 prints a subchart's defaults, which is the reference for what you may override.