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---
63 lines
5.0 KiB
Markdown
63 lines
5.0 KiB
Markdown
# Kustomize — 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 `helm.md`.
|
|
|
|
## What Kustomize Is (P1 Declarative Desired State)
|
|
|
|
- Kustomize customizes manifests without templating. A base directory holds the canonical manifests; overlays hold the deltas. The result is plain YAML applied with `kubectl apply -k`.
|
|
- No DSL, no template language, no rendering step hidden from `kubectl`. The patch is a YAML file; the result is inspectable.
|
|
- Kustomize is built into `kubectl` (`kubectl apply -k`, `kubectl diff -k`). No separate runtime is required to apply.
|
|
|
|
## Base and Overlays (P6 Namespaces Bound Blast Radius, C4 Locality)
|
|
|
|
- A `kustomization.yaml` in a base directory lists the resources (Deployment, Service, etc.) the application needs. It is the canonical manifest.
|
|
- An overlay is a directory with its own `kustomization.yaml` that references the base (`resources: - ../../base`) and applies patches or additional resources.
|
|
- Typical structure: `base/`, `overlays/dev/`, `overlays/staging/`, `overlays/prod/`. The overlay is the environment axis; the base is the shared truth.
|
|
|
|
## Patches (P1 Declarative Desired State, C2 Clarity)
|
|
|
|
- Strategic merge patches — a YAML document that overrides matching fields. Simple for single-resource changes.
|
|
- JSON patches (RFC 6902) — precise operations (`add`, `replace`, `remove`) on a path. Use when a strategic merge is ambiguous (e.g., list operations).
|
|
- `patches` field (modern) takes a list of patch files with targets, replacing the older `patchesStrategicMerge` and `patchesJson6902`. Prefer it.
|
|
- A patch is a delta. It is reviewed as "what changes from base," which is exactly the diff a reviewer wants to see.
|
|
|
|
## Generators and Transformers (P3 Labels Select)
|
|
|
|
- `configMapGenerator` and `secretGenerator` create ConfigMaps and Secrets from files or literals, with content hashes in the names. A change to the source file changes the hash, which changes the name, which rolls the workload. This is the kustomize pattern for "config change = redeploy."
|
|
- `namePrefix`, `nameSuffix`, and `namespace` transformers rewrite names across the base. Use for namespace isolation (P6) or to run the same base multiple times in one cluster without collisions.
|
|
- `commonLabels` and `commonAnnotations` stamp labels onto everything in the base — the kustomize-native way to enforce the labelling discipline of P3.
|
|
|
|
## No Release Tracking (P10 Roll Forward Roll Back)
|
|
|
|
- Kustomize has no release object, no history, no built-in rollback. `kubectl apply -k` is a one-shot apply; the previous state is in git, not in a Helm-style release record.
|
|
- Rollback is `git revert` + `kubectl apply -k`. The git history IS the release history. This is fine — and arguably cleaner — but it means rollback is a git operation, not a `helm rollback` command.
|
|
- Use a GitOps tool (ArgoCD, Flux) on top of Kustomize for automated reconciliation and rollback tracking. The tool watches the git ref; rollback is a git revert.
|
|
|
|
## Helm vs Kustomize — Decision Matrix (IDEATE-10)
|
|
|
|
| Axis | Kustomize | Helm |
|
|
|------|----------|------|
|
|
| Mechanism | Overlays (base + patches) | Templating (Go templates) |
|
|
| Reuse unit | Base directory (kustomization.yaml) | Chart (versioned package) |
|
|
| Distribution | Git (base dir in a repo) | Registry (OCI, chart repo) |
|
|
| Values | `kustomization.yaml` + patches | `values.yaml` + overrides |
|
|
| Release mgmt | None native — `kubectl apply -k` | `helm` tracks releases, history, rollback |
|
|
| Learning curve | YAML patching, no DSL | Template language to learn |
|
|
| Blast radius | One base, many overlays, patched | One chart, many resources, templated |
|
|
| Best for | Internal apps, patching upstream manifests, env-specific deltas | Off-the-shelf apps, packaged stacks, multi-env via values |
|
|
| Watch out for | No release tracking, manual rollback, patch sprawl | Template complexity, `latest` chart drift, secrets in values |
|
|
|
|
- Use Kustomize when you patch existing manifests or keep env deltas in one repo. Use Helm when you distribute a reusable app or consume third-party charts.
|
|
- Mixing both is fine and common: Kustomize for the internal apps, Helm for the packaged parts. The decision is per-workload, not per-cluster.
|
|
- `commonLabels` is the kustomize-native enforcement of P3 (Labels Select); see `domains/devops/first-principles.md` P6 (Configuration as Code) for the upstream principle that the rendered manifest — not a console click — is the source of truth.
|
|
|
|
## What Violates Kustomize Discipline
|
|
|
|
| Violation | Principle |
|
|
|-----------|-----------|
|
|
| Duplicated base instead of an overlay | P6 Modules Compose (use an overlay) |
|
|
| Patch that overrides most of the base | C3 Simplicity (the base is wrong — fix the base) |
|
|
| No `commonLabels` on a multi-team base | P3 Labels Select |
|
|
| No git-based rollback strategy | P10 Roll Forward Roll Back |
|
|
| Hand-edited rendered output instead of `apply -k` | P1 Declarative Desired State |
|
|
| Patch sprawl (10 overlays each patching 15 fields) | C3 Simplicity (refactor the base) | |