Kubernetes Helm Package Model

Kubernetes Helm Package Model is the specific structure Helm imposes on the general template-values-render packaging pattern: a chart directory containing Go-template manifests and a Chart.yaml metadata file, rendered against a values.yaml file and any user-supplied overrides, tracked in-cluster as a named, versioned Release with a full, append-only revision history enabling rollback.

Chart Structure

The Standard Chart Layout

mychart/
  Chart.yaml
  values.yaml
  templates/
    deployment.yaml
    service.yaml
    _helpers.tpl
  charts/
    postgresql/

Chart.yaml declares the chart's own name, version, and appVersion; values.yaml provides default values for every parameter the templates reference; templates/ holds the Go-template manifest files themselves; and charts/ holds vendored subchart dependencies, together forming a single self-contained, distributable unit.

apiVersion: v2
name: mychart
version: 1.2.0
appVersion: "2.0.1"

The Release as Tracked State

What a Release Records

helm install my-app ./mychart -f values-production.yaml

Installing a chart creates a Release, an in-cluster record (stored as Secret objects by default in Helm 3) capturing the exact chart version, the exact resolved values used, and the exact rendered manifest set applied, giving Helm the information needed to compute a diff for the next upgrade or to reconstruct a prior state for rollback.

kubectl get secrets -l owner=helm,name=my-app

Client-Only Architecture

Unlike Helm 2's server-side Tiller component, Helm 3 performs all rendering and API interaction directly from the client using the user's own kubeconfig credentials and RBAC permissions, removing the need for a cluster-resident, highly privileged Helm-specific service and instead relying entirely on standard Kubernetes API access already governed by existing RBAC.

Revision History and Rollback

Append-Only Revisions

helm history my-app
REVISION   STATUS       CHART            APP VERSION
1          superseded   mychart-1.0.0    1.9.0
2          superseded   mychart-1.1.0    2.0.0
3          deployed     mychart-1.2.0    2.0.1

Each helm upgrade creates a new revision rather than overwriting the previous one's record, and helm rollback my-app 2 reapplies exactly the rendered manifests recorded for revision 2, which is only possible because that revision's complete rendered output, not merely its source values, was preserved at install time.

Three-Way Strategic Merge on Upgrade

Computing the Applied Diff

helm upgrade my-app ./mychart -f values-production.yaml

An upgrade computes a three-way merge between the previous revision's rendered manifests, the current live state of the cluster's objects, and the newly rendered manifests, allowing changes made outside Helm (an autoscaler's replicas adjustment, for instance) to be preserved where the new chart revision does not explicitly override them, similar in spirit to kubectl apply's own three-way merge but computed against Helm's own tracked prior state rather than the annotation-based mechanism kubectl uses.

Hooks as Lifecycle Extension Points

Ordered Actions Around Install and Upgrade

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    helm.sh/hook: pre-upgrade
    helm.sh/hook-weight: "0"

Hooks let a chart declare resources that run at specific points relative to the main install or upgrade action, pre-install, post-install, pre-upgrade, pre-delete, with helm.sh/hook-weight controlling execution order among multiple hooks at the same lifecycle point, encoding imperative sequencing the underlying declarative manifest model cannot express on its own.

Uninstallation and State Cleanup

Removing a Release

helm uninstall my-app

Uninstalling deletes every resource recorded as belonging to the release and removes the release's own tracked history by default, though --keep-history retains the revision records (without the deployed resources) specifically to support inspecting what was previously installed even after the resources themselves are gone.

Relationship to the Broader Packaging Model and Kustomize Comparison

The Helm package model is a specific, templating-based instantiation of the general packaging model already introduced, distinguished from the Kustomize package model's patch-based approach by its use of a Go-template rendering engine, its in-cluster release tracking with full revision history, and its lifecycle hooks; both models solve the same underlying template-values-render problem, but Helm's release and rollback machinery gives it stronger built-in support for tracking exactly what was deployed and reverting to a prior state, at the cost of introducing a templating language's own learning curve and failure modes into what would otherwise be plain YAML.