Jon Chery
d1aa5daf2b
---ci--- project: atelier phase: 5 milestone: v0.2 status: complete requirements: covered: [ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40, ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47, ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56, ATELIER-57, ATELIER-58, ATELIER-59] partial: [] ---/ci---
68 lines
4.8 KiB
Markdown
68 lines
4.8 KiB
Markdown
# 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 | |