atelier/domains/kubernetes/helm.md

Helm — Derived Rules

Derives from domains/kubernetes/first-principles.md. Applies P1, P3, P6. For the Helm-vs-Kustomize decision, see the decision matrix at the end of this doc and in kustomize.md.

What Helm Is (P6 Modules Compose)

• Helm is a package manager for Kubernetes. A chart is a versioned package of templated manifests. helm install renders the templates against values.yaml and applies the result.
• A chart encapsulates a reusable deployment (an application, a database, a full stack). It is the k8s analogue of an IaC module — see domains/infrastructure-as-code/modules.md.
• Charts live in registries (Helm registry via OCI, or the classic chart repos) and are versioned per SemVer.

Chart Structure (P1 Declarative Desired State, C2 Clarity)

• Chart.yaml — metadata (name, version, appVersion, dependencies).
• values.yaml — default inputs; the chart's public interface.
• templates/ — Go-templated manifests. templates/_helpers.tpl holds reusable template partials.
• values.schema.json — optional schema for values, giving type checking on inputs. Use it for published charts.
• A chart should have one logical purpose. A chart that deploys an app and a database and an ingress and an observability stack has too many jobs — split it.

Values (P5 Version Everything, C2 Clarity)

• values.yaml holds defaults. Override per release: helm install --set key=value or helm install -f my-values.yaml.
• Pin values files in git per environment. A release is reproducible from the chart version + the values file.
• Sensitive values do not belong in values.yaml. Inject via Secrets (see rbac.md P9 and domains/security/secrets.md). Some charts accept existingSecret to reference a pre-created Secret.

Release Management (P5 Version Everything, P10 Roll Forward Roll Back)

• A release is a named instantiation of a chart. helm upgrade applies a new chart version or new values. helm rollback reverts to the previous release revision.
• helm history <release> lists revisions; helm rollback <release> <revision> is the rollback. The rollback must be tested like any deploy (P10).
• Pin the chart version: helm install --version 1.2.3. Never --version latest in production — unversioned charts drift (same anti-pattern as unpinned IaC modules).

Templating Discipline (P1 Declarative Desired State, C2 Clarity)

• Templates render to valid manifests. The chart author's job is that the rendered output is correct k8s, not that the template is clever.
• Keep templates/ readable. Heavy logic belongs in _helpers.tpl or in a values structure that the template merely projects.
• helm template renders to stdout without applying — use it to review what a release will create before installing it.

Registries (P5 Version Everything)

• OCI registries are the modern chart distribution (same registry as container images, charts as OCI artifacts). Classic chart repos are legacy.
• Pull from a pinned registry reference: oci://registry/chart:1.2.3. The digest + tag is the version.

Helm vs Kustomize — Decision Matrix (IDEATE-10)

Axis	Helm	Kustomize
Mechanism	Templating (Go templates)	Overlays (base + patches)
Reuse unit	Chart (versioned package)	Base directory (kustomization.yaml)
Distribution	Registry (OCI, chart repo)	Git (base dir in a repo)
Values	values.yaml + overrides	kustomization.yaml + patches
Release mgmt	helm tracks releases, history, rollback	None native — apply with kubectl apply -k
Learning curve	Template language to learn	YAML patching, no DSL
Blast radius	One chart, many resources, templated	One base, many overlays, patched
Best for	Off-the-shelf apps, packaged stacks, multi-env via values	Internal apps, patching upstream manifests, env-specific deltas
Watch out for	Template complexity, latest chart drift, secrets in values	No release tracking, manual rollback, patch sprawl

• Use Helm when you distribute a reusable app or consume third-party charts. Use Kustomize when you patch existing manifests or keep env deltas in one repo.
• Mixing both is fine and common: Helm for the packaged parts, Kustomize for the last-mile per-env patching. Do not fight the tool that fits the job.

What Violates Helm Discipline

Violation	Principle
helm install --version latest in prod	P5 Version Everything
Secrets in values.yaml	P9 Config and Secrets are Separate, security
Chart with 15 subcharts doing unrelated things	P6 Modules Compose (split it)
No values.schema.json on a published chart	C2 Clarity
helm upgrade without reviewing helm template output	P1 Declarative Desired State, P4 Plan Before Apply
Untested helm rollback	P10 Roll Forward Roll Back