Ensuring Deterministic Helm Deployments with Chart.lock

The Problem: Version Drift in Kubernetes Deployments

When a Helm chart relies on sub-charts (dependencies), using flexible version ranges in Chart.yaml (such as ^1.2.0) introduces a risk: the version of a dependency resolved during a developer's local test may differ from the version resolved during a production CI/CD pipeline run. This "version drift" can lead to unexpected breaking changes in production that were never validated in staging.

The solution is to move from dynamic resolution to deterministic locking using the Chart.lock file. This ensures that every environment deploys the exact same binary version of every dependency.

The Smallest Suitable Design for Dependency Locking

To implement deterministic deployments, you must separate the declaration of a dependency from the locking of that dependency. The architecture relies on three components:

• Chart.yaml: Defines the required dependency and the allowed version range.
• Chart.lock: A generated file that records the specific version and digest (hash) of the resolved dependency.
• charts/ directory: The local storage where the resolved .tgz packages are cached before packaging.

Implementation Workflow

Run these commands from the root of your chart directory. You will need the Helm CLI installed and access to the remote repositories defined in your configuration.

1. Declare the dependency in Chart.yaml:

   dependencies:
     - name: redis
       version: "^17.0.0"
       repository: "https://charts.bitnami.com/bitnami"

2. Resolve and lock the versions by running:

   helm dependency update

   Risk: This command connects to the internet. If the repository is unavailable, the command will fail. This is the only stage where version ranges are evaluated.

3. Commit the lock file: Add Chart.lock to your version control system (Git). Do not commit the charts/ directory, as it contains binary blobs that bloat the repository.

4. Enforce the lock in CI/CD pipelines using:

   helm dependency build

   Unlike update, build strictly adheres to the Chart.lock file. If the lock file is missing or inconsistent with the Chart.yaml, the build will fail rather than silently updating to a newer version.

Trust and Data Boundaries

The trust boundary exists between the Helm client and the remote chart repository. When helm dependency update runs, it fetches the chart and calculates a digest. This digest is stored in Chart.lock.

During the build phase, Helm verifies that the downloaded package matches the digest in the lock file. This prevents "man-in-the-middle" attacks or repository overrides where a chart version is replaced with a different binary under the same version number.

Operational Checks and Verification

To verify that your locking mechanism is working, perform the following diagnostic check:

Step	Action	Expected Result
1. Baseline	Run helm dependency update	Chart.lock is created with a specific version (e.g., 17.1.2).
2. Drift Test	Wait for a new sub-chart release (e.g., 17.1.3)	Remote repo now has a newer version matching the ^17.0.0 range.
3. Build Test	Run helm dependency build	The charts/ directory contains 17.1.2, not 17.1.3.

Failure Modes and Design Constraints

• Circular Dependencies: Helm does not support charts that depend on each other (Chart A → Chart B → Chart A). This will result in a resolution error during the update phase.
• Network Isolation: Since resolution happens client-side, the CI/CD runner must have network access to the chart repositories. If the environment is air-gapped, you must package the chart into a .tgz archive including the charts/ folder, bypassing the lock mechanism entirely.
• Lock File Desync: If a developer updates Chart.yaml but forgets to run update and commit the Chart.lock, the CI/CD pipeline using helm dependency build will fail. This is a desired failure, as it prevents unverified version changes from reaching production.

Conditions for Changing This Design

This lock-file approach is suitable for most standard deployments. However, you should move to a different strategy (such as an internal OCI registry or fully bundled charts) if:

• You require 100% availability of dependencies without relying on external third-party repositories.
• You are managing a massive number of micro-charts where the overhead of managing individual lock files becomes a bottleneck.
• You need to perform dynamic versioning based on environment variables (which Helm's static Chart.yaml does not support).