Helm Chart Dependencies: Refactoring Patterns That Help and Ones That Hurt

Helm Chart Dependencies: Refactoring Patterns That Help and Ones That Hurt

Reading time1 min
#helm#kubernetes#devops#charts#refactoring

Helm Chart Dependencies: Refactoring Patterns That Help and Ones That Hurt

Helm dependencies look simple: list subcharts in Chart.yaml, run helm dependency update, ship one release. In practice, chart structure decides how you deploy, roll back and debug. A good refactor removes copy-paste and makes upgrades predictable. A bad one renames resources, loses data or ties unrelated services to one release.

How dependencies work

In Helm 3 and later (chart apiVersion: v2), dependencies live in Chart.yaml. The old requirements.yaml is Helm 2.

apiVersion: v2
name: my-platform
version: 1.4.0
dependencies:
  - name: my-api
    version: "2.3.1"
    repository: "oci://registry.example.com/charts"
    alias: api
  - name: my-worker
    version: "~1.8.0"
    repository: "oci://registry.example.com/charts"
    condition: worker.enabled
  - name: common
    version: "1.x.x"
    repository: "file://../common"
  • helm dependency update resolves version ranges, downloads the charts into charts/ and writes Chart.lock.
  • helm dependency build rebuilds charts/ from Chart.lock exactly. Use it in CI so builds are reproducible, and commit Chart.lock.
  • Values for a subchart go under its name or alias (api: in the example above). A subchart cannot read the parent's values, except anything under global.
  • condition and tags turn subcharts on and off per environment.

Two behaviors cause most of the surprises.

Named templates are global. Templates from the parent and all subcharts are loaded together. If two charts define a template with the same name, the last one loaded wins. Always prefix template names with the chart name.

CRDs in crds/ are installed once. Helm installs them on the first install and never upgrades or deletes them. If a dependency ships CRDs that way, upgrading the dependency does not upgrade its CRDs. Manage those CRDs separately.

Refactors that usually help

Library chart for shared helpers. If every service chart has its own copy of _helpers.tpl, labels and probes, move them to a chart with type: library. Library charts render nothing on their own; consumers include their templates. One fix then reaches every service on its next version bump.

Pinned versions plus a lock file. Ranges like ~1.8.0 are fine in Chart.yaml as long as Chart.lock is committed and CI uses helm dependency build. Without the lock, two builds of the same commit can pull different subchart versions.

OCI registry instead of file://. file:// dependencies are packaged into charts/ when you run helm dependency update. If someone edits the local chart and forgets to update, the parent ships the old copy. Publishing subcharts to an OCI registry with real versions removes that class of mistakes.

Render and validate in CI. Lint, render with each environment's values and validate the output against the target Kubernetes version:

helm dependency build ./my-platform
helm lint ./my-platform -f values-prod.yaml
helm template my-platform ./my-platform -f values-prod.yaml \
  | kubeconform -strict -summary -kubernetes-version "$K8S_VERSION" -ignore-missing-schemas

Set K8S_VERSION to the cluster's version, for example 1.35.0. -ignore-missing-schemas lets CRDs through, but it also hides APIs removed in that version, so pair it with a deprecated API checker such as pluto.

kubeval is no longer maintained; kubeconform is the usual replacement. Add helm diff upgrade (helm-diff plugin) to pull requests so reviewers see the actual change to the cluster, not just the change to templates.

One release per independently deployed service. An umbrella chart is one Helm release. Every upgrade touches every subchart, and helm rollback rolls all of them back together. If services are deployed on their own schedule, give each one its own release and handle ordering in your GitOps tool (Argo CD sync waves, Flux dependsOn). Keep umbrella charts for things that really ship as one unit, such as an app plus its own cache.

Refactors that tend to hurt

Renaming the release or changing the naming helper. Resource names usually come from a fullname helper that includes the release name. Installing under a new release name, or changing that helper, produces Deployments, Services and StatefulSets with new names, and the old ones are deleted on upgrade or uninstall. For a StatefulSet, PVC names include the StatefulSet name, so the new pods get new empty volumes. Before renaming, render both versions and compare resource names.

Moving resources between releases. Helm refuses to take over a resource that another release owns. Adopting it requires the annotations meta.helm.sh/release-name and meta.helm.sh/release-namespace and the label app.kubernetes.io/managed-by: Helm set to the new owner. Plan the move: annotate first, then remove the resource from the old chart, then upgrade.

Changing immutable fields. Moving labels around during a refactor often changes a Deployment's spec.selector or a StatefulSet's volumeClaimTemplates. Both are immutable, so the upgrade fails halfway. Keep selector labels stable forever.

Deep nesting. A subchart of a subchart of an umbrella chart means values paths like platform.backend.api.image.tag, and template errors that point to files you have never opened. Two levels is usually the limit before debugging gets painful.

Very large umbrella charts. By default Helm stores each release revision in a Secret, and a Secret is limited to 1 MiB. A big enough umbrella chart fails to install for that reason alone.

Expecting rollback to undo everything. helm rollback reapplies old manifests. It does not undo database migrations, CRD changes or data written by the new version. Treat rollback as a deploy of the old version, and test it.

Safe upgrade flags

helm upgrade --install --wait waits until resources are ready. To roll back automatically on failure, use --atomic in Helm 3; Helm 4 renamed it to --rollback-on-failure. Set --timeout to something longer than your slowest rollout.

Checklist

  • Dependencies in Chart.yaml, Chart.lock committed, helm dependency build in CI.
  • Template names prefixed with the chart name; shared helpers in a library chart.
  • CRDs managed outside crds/ if they need upgrades.
  • helm lint, helm template and kubeconform for every environment's values.
  • helm diff output in every pull request.
  • Before any rename or move: compare rendered resource names and plan Helm ownership annotations.
  • One release per independently deployed service.