Understanding Helm Fundamentals

1. Understanding Helm Architecture

Component	Role	Location
Helm CLI	Client-side binary (Go) that renders charts and talks to Kubernetes API	Developer workstation / CI runner
Chart	Packaged collection of templated Kubernetes manifests + metadata	Local FS, repository, or OCI registry
Release	Named instance of a chart installed into a cluster	Kubernetes Secret (driver=secrets) in release namespace
Repository	HTTP server or OCI registry hosting packaged charts + index.yaml	Static site / ChartMuseum / Harbor / GHCR / ECR
Kubernetes API	Target where rendered manifests are applied via three-way merge	Cluster API server

Helm 3 Client-Only Flow

Developer → helm CLI → render templates (local)
                          ↓
                    K8s API server → etcd (manifests + Release Secret)

Note: Helm 3 removed Tiller. All authorization is delegated to the user's kubeconfig RBAC.

2. Understanding Chart Concept

File / Dir	Required	Purpose
`Chart.yaml`	Yes	Metadata: name, version, appVersion, dependencies
`values.yaml`	Yes	Default configuration values
`templates/`	Yes	Go template files rendered into K8s manifests
`charts/`	No	Vendored subchart dependencies
`crds/`	No	CustomResourceDefinitions installed before templates
`templates/NOTES.txt`	No	Post-install user instructions
`templates/_helpers.tpl`	No	Named template partials (not rendered directly)
`values.schema.json`	No	JSON Schema validation for values
`.helmignore`	No	Files excluded from packaging

3. Understanding Release Concept

Attribute	Description
Name	Unique per namespace; DNS-1123 label
Revision	Monotonically increasing integer per install/upgrade/rollback
Status	`deployed`, `failed`, `pending-upgrade`, `superseded`, `uninstalled`
Storage	Kubernetes Secret `sh.helm.release.v1.<name>.v<rev>`
History limit	Default 10 revisions retained (`--history-max`)

4. Understanding Repository Concept

Type	Protocol	Index
HTTP repo	HTTPS GET	`index.yaml` at repo root
OCI registry STABLE 3.8+	OCI distribution spec	No index; uses registry tag listing
Git (plugin)	Git over SSH/HTTPS	Via `helm-git` plugin
Local path	Filesystem	None; direct chart reference

5. Understanding Values Hierarchy

Priority (low → high)	Source
1	Subchart `values.yaml`
2	Parent chart `values.yaml`
3	`-f` / `--values` files (in order)
4	`--set`, `--set-string`, `--set-file`, `--set-json`

Note: Later sources override earlier; maps merge deeply, lists replace entirely.

6. Understanding Template Rendering

Render Pipeline

Load chart + dependencies into memory
Merge values (chart defaults → user values → --set)
Validate against values.schema.json if present
Execute Go templates with Sprig + Helm functions
Parse YAML; separate hooks from regular resources
Send to Kubernetes API via three-way merge

7. Understanding Chart Lifecycle

Lifecycle States

install → [deployed] → upgrade → [deployed]
                ↓                       ↓
            rollback ← ← ← ← ← ← ← failed
                ↓
            uninstall → [uninstalled / purged]

8. Understanding Helm Three-Way Merge

Source	Role in Merge
Old manifest	Previous release revision stored in Helm Secret
New manifest	Newly rendered output from upgrade
Live state	Current object in cluster (captures drift)

Note: Helm 3 detects drift by comparing live state to old manifest, then computes patch from new manifest — preventing accidental overwrite of out-of-band edits to fields Helm doesn't manage.

9. Understanding Chart API Versions

apiVersion	Helm	Dependencies
`v1` LEGACY	Helm 2	`requirements.yaml` (external file)
`v2` CURRENT	Helm 3+	`dependencies:` in `Chart.yaml`; supports `type: library`

10. Comparing Helm vs Kustomize

Helm

Templated (Go templates + Sprig)
Package manager: versioning, repos, releases, rollback
Conditional logic, loops, dependencies
Steeper learning curve; whitespace pitfalls
Best for: distributable apps, complex parameterization

Kustomize

Overlay-based (no templates)
Pure YAML patches (strategic / JSON 6902)
No release tracking; kubectl apply driven
Simpler; built into kubectl
Best for: environment overlays of internal manifests

Note: They compose — use Kustomize as a Helm post-renderer for cluster-specific patches.

Related Cheat Sheets

Kubernetes