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.jsonif 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
Note: They compose — use Kustomize as a Helm post-renderer for cluster-specific patches.