atelier/domains/kubernetes/kustomize.md

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.

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)