Kubernetes Helm Dependency Management

Kubernetes Helm Dependency Management streamlines package dependencies, ensuring consistent and scalable deployments across containerized applications.

Kubernetes Helm Dependency Management is the practice of declaring, resolving, and version-locking a chart's dependencies on other charts, covering semantic version range matching, the Chart.lock file that pins exact resolved versions, aliasing for installing the same subchart multiple times, conditional inclusion via condition and tags, and the umbrella chart pattern for composing an entire application from independently maintained charts.

Declaring Dependencies

The dependencies Field

apiVersion: v2
name: myapp
dependencies:
  - name: postgresql
    version: "~12.1.0"
    repository: "https://charts.bitnami.com/bitnami"
  - name: redis
    version: "^17.0.0"
    repository: "https://charts.bitnami.com/bitnami"

Each dependency entry specifies the subchart's name, a semantic version range, and the repository it can be fetched from; ~12.1.0 permits patch-level updates only (12.1.x), while ^17.0.0 permits any minor or patch update within the same major version (17.x.x), giving explicit control over how much automatic drift a dependency can absorb between resolution runs.

~12.1.0 \to [12.1.0, 12.2.0),^17.0.0 \to [17.0.0, 18.0.0)

Resolving and Locking Dependencies

update vs. build

helm dependency update ./mychart

helm dependency update resolves each declared version range against the repository, downloads the matching chart archives into charts/, and writes (or refreshes) a Chart.lock file recording the exact version actually resolved for each dependency.

helm dependency build ./mychart

helm dependency build, by contrast, uses the existing Chart.lock file to fetch the exact previously locked versions without re-resolving version ranges, the dependency equivalent of installing from a lockfile rather than re-running a resolver, which is the appropriate command for CI pipelines that must reproduce a known-good dependency set exactly.

# Chart.lock
dependencies:
  - name: postgresql
    repository: https://charts.bitnami.com/bitnami
    version: 12.1.9
digest: sha256:...

build = Fetch(Chart.lock), update = Resolve(dependencies) → Chart.lock

Aliasing for Multiple Instances

Installing the Same Subchart Twice

dependencies:
  - name: redis
    version: "17.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    alias: cache-redis
  - name: redis
    version: "17.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    alias: session-redis

cache-redis:
  auth:
    enabled: false
session-redis:
  auth:
    enabled: true

alias lets the identical subchart be included twice under different names, each independently configurable through its own values namespace, solving the case where an application genuinely needs two separately configured instances of the same underlying chart, a cache instance and a session-store instance of Redis, for example, without duplicating the subchart's own source.

Conditional Dependency Inclusion

condition and tags

dependencies:
  - name: postgresql
    version: "12.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
    tags:
      - database

postgresql:
  enabled: false

helm install my-app ./mychart --set tags.database=false

condition ties a single dependency's inclusion to a specific boolean values path, while tags group several dependencies together under a shared toggle, letting an installation disable an entire category of optional dependencies (every chart tagged database, for instance) with a single flag rather than toggling each dependency's condition individually.

Library Charts for Shared Template Logic

Charts That Produce No Resources Directly

apiVersion: v2
name: common-templates
type: library

dependencies:
  - name: common-templates
    version: "1.x.x"
    repository: "https://charts.example.com"

A type: library chart provides only named template definitions (helper functions, common label templates) for other charts to include, and produces no Kubernetes resources when included as a dependency, functioning purely as a shared code library across an organization's multiple application charts rather than as an installable component itself.

The Umbrella Chart Pattern

Composing a Full Application from Independent Charts

apiVersion: v2
name: myapp-platform
dependencies:
  - name: web
    version: "1.x.x"
    repository: "file://../web-chart"
  - name: worker
    version: "1.x.x"
    repository: "file://../worker-chart"
  - name: postgresql
    version: "12.x.x"
    repository: "https://charts.bitnami.com/bitnami"

An umbrella chart contains no templates of its own beyond perhaps a shared ConfigMap, existing purely to declare and version-pin a coherent set of dependencies, letting an entire multi-component application be installed, upgraded, and versioned as a single release while each component chart remains independently developed, tested, and reusable in other contexts outside this specific umbrella.

Relationship to the Helm Package Model and Values Management

Dependency management extends the single-chart template-values-render pattern described under the Helm package model into a composed, multi-chart structure, and it directly interacts with the global values mechanism covered under Helm values management, since dependency resolution determines which subchart versions are actually present to receive those shared global values at render time, making the Chart.lock file the concrete record of exactly which composed set of chart versions any given release was built from.