Helm / Intermediate: authoring and lifecycle contracts / Lesson 9

Dependencies, subcharts and locks

Compose application charts with explicit dependency interfaces, resolved versions and reproducible artifacts while avoiding accidental parent coupling.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish dependency declaration, resolution and packaged contents.
Trace parent overrides into subchart values.
Review aliases, conditions and global values as interfaces.

Separate declaration from resolution

Chart.yaml can declare dependencies with names, version constraints and repository locations. A constraint expresses acceptable versions; it does not by itself identify the exact bytes used in a release. Chart.lock records resolved dependency versions and related lock metadata, while charts contains the dependency artifacts used for packaging. Review these layers together. Changing a constraint without reconciling the lock and bundled artifacts creates ambiguity. Reproducible review needs a known chart archive and known dependencies, not a promise that a remote repository will keep presenting the same mutable contents under a familiar name.

Declare a local teaching dependency

The first fragment declares a synthetic metrics chart available from a sibling source directory. A file repository is useful for explaining composition without fetching a real service, but the path is an authoring assumption and must exist in a real isolated build. The condition points to a boolean in parent values. Dependencies may still need to be available during chart processing even when their resources are disabled, so do not treat a condition as permission to omit artifact management. Here the fragment remains unexecuted and no dependency command is run.

yaml Chart.yaml dependency fragment

dependencies:
  - name: metrics
    version: "1.2.3"
    repository: "file://../metrics"
    condition: metrics.enabled

The example pins an illustrative dependency version and uses no public registry or credentials. It is not a complete parent chart.

Trace values through scopes

An application subchart is designed to be usable independently and cannot simply read arbitrary parent values. The parent overrides it under the dependency name, or alias when one is used. Inside the subchart, that nested map becomes the subchart’s own Values root. In the second fragment, parent metrics.intervalSeconds becomes .Values.intervalSeconds in metrics templates. It does not become .Values.metrics.intervalSeconds there. Global values are an explicit shared channel, but broad use increases coupling. Share only values with a clearly common meaning, such as an agreed registry prefix, rather than duplicating every parent setting globally.

yaml Parent values for a subchart

metrics:
  enabled: true
  intervalSeconds: 30
global:
  teachingEnvironment: synthetic

Within metrics, the documented inputs are enabled, intervalSeconds and global.teachingEnvironment. The subchart must explicitly consume each relevant value.

Review aliases and ownership

An alias allows one dependency chart to appear more than once with separate configuration paths. That does not automatically guarantee unique Kubernetes names; the subchart’s naming helpers still determine resource identities. Two aliases that render a fixed ConfigMap name can collide. Similarly, enabling a bundled database changes more than convenience: it assigns lifecycle and storage expectations to the release. Choose whether a dependency is part of the application’s recoverable unit or an external prerequisite. Do not bundle a stateful service merely because a sample chart offers an enabled flag; its ownership and recovery need explicit design.

Distinguish updating from rebuilding

Dependency update resolves declarations and can produce a new lock, while dependency build is intended to reconstruct dependencies from an existing lock when present. Neither action alone establishes artifact trust or application compatibility. Review a dependency change as third-party code and configuration change: inspect generated resources, helper names, values defaults and required permissions. Keep an offline artifact inventory with exact identities for the synthetic review. This course executes neither command and contacts no repository. A future authorized build must record what it fetched and how those bytes were approved before calling the result reproducible.

Common errors and fixes

The subchart cannot find .Values.metrics.intervalSeconds

Why it happens: The parent nesting was repeated inside the subchart scope.
How to fix it: Read .Values.intervalSeconds inside metrics and keep the parent override under metrics.
Prevent it next time: Document both parent and child views of the values interface.

Two aliases render the same fixed object name

Why it happens: Aliases were assumed to rewrite template naming automatically.
How to fix it: Review subchart naming inputs and ensure distinct intended identities.
Prevent it next time: Render a two-alias fixture during dependency review.

A build changes dependencies unexpectedly

Why it happens: An update operation re-resolved constraints instead of using an approved lock.
How to fix it: Restore the approved declaration, lock and artifacts, then investigate the changed resolution.
Prevent it next time: Separate dependency refresh approval from ordinary artifact reconstruction.

Check your understanding

1. Parent values have metrics.intervalSeconds 30. What should a metrics template read, and why?

Show worked solution

They read .Values.intervalSeconds because Helm supplies the dependency-specific map as that subchart’s values scope. The parent remains responsible for placing overrides under the dependency name or alias. This separation supports standalone use: the subchart does not need to know which parent includes it or how unrelated parent values are organized.

2. A lock pins a dependency version. What evidence is still needed before distributing the parent?