Helm State Model

Helm State Model defines the conceptual framework that describes how Helm manages and tracks the lifecycle and current state of Kubernetes resources deployed through Helm charts. It encapsulates the mechanisms Helm employs to record, compare, and reconcile the desired state of applications with the actual state running in a Kubernetes cluster, enabling reliable and consistent deployment, upgrade, and rollback operations.

Core Concepts of the Helm State Model

Desired State

The desired state in Helm is embodied by the chart templates combined with the supplied values during installation or upgrade. This desired state represents the configuration and resources that the user intends to be running in the cluster. Helm processes the chart’s templates with values to generate Kubernetes manifests that define the desired cluster objects.

Actual State

The actual state refers to the live resources currently deployed and running in the Kubernetes cluster. These resources include Pods, Services, ConfigMaps, Deployments, and other Kubernetes API objects created as a result of applying Helm manifests.

Release Object

A Helm release is the instantiation of a chart deployed to a Kubernetes cluster. Each release has an associated release object stored in the cluster, which contains metadata such as the release name, namespace, revision history, chart version, configuration values, and the computed manifests.

The release object acts as the primary record Helm uses to track the state of an application. It serves as the basis for Helm’s state comparisons during upgrades or rollbacks.

Helm Release Storage and State Persistence

Release Records

Helm persists the release state in Kubernetes as ConfigMaps or Secrets within the target namespace (depending on Helm version and configuration). These records store:

• The full rendered manifests applied to the cluster.
• The user-supplied values used during deployment.
• Metadata including release name, namespace, and revision number.
• Hooks information and lifecycle events.

This persistent storage enables Helm to reconstruct the previous state of a release at any revision, facilitating upgrades and rollbacks.

Revision History

Each time a release is installed or upgraded, Helm increments the release revision and stores a new release record. This revision history preserves the state differences between deployments, allowing Helm to manage state transitions correctly.

State Transitions and Reconciliation

Installation

During installation, Helm generates manifests from chart templates and provided values, applies these manifests to the cluster, and stores the resulting release object. The state transition moves from no release record to a new release reflecting the desired deployed state.

Upgrade

When upgrading, Helm compares the new desired state generated from the updated chart and values against the stored release state. Helm calculates the difference (diff) and applies only the necessary Kubernetes API changes to move the actual state toward the new desired state. The updated release record is then saved with an incremented revision.

Rollback

Rollback uses the release revision history to revert the application to a previous known good state. Helm retrieves the manifests from a prior revision and reapplies them, overwriting the current actual state with that previous desired state. The rollback also creates a new revision record reflecting this state change.

State Integrity and Conflict Handling

Three-Way Strategic Merge Patch

Helm leverages Kubernetes’ three-way strategic merge patch to reconcile changes. This involves computing differences between:

• The last deployed manifest (stored release state),
• The new desired manifest,
• The current live manifest in the cluster.

This approach helps Helm intelligently merge changes, preserve user modifications to resources where appropriate, and avoid overwriting unrelated changes made outside Helm.

Hooks and Lifecycle Events

Helm integrates hooks (pre-install, post-install, pre-upgrade, post-upgrade, etc.) into the state model by tracking their execution status within release records. This ensures that the release state reflects not only the Kubernetes objects but also the successful completion of lifecycle events necessary for a consistent application state.

Summary of the Helm State Model Components

Helm’s state model is fundamental for enabling declarative application management, ensuring that deployments are reproducible, traceable, and maintainable over time. It provides the basis for Helm’s core functionality in managing complex Kubernetes applications through versioned, atomic, and consistent state transitions.