tomevault-io Kubernetes Kustomize Review
Overview
Reviews Kustomize overlay structure and best practices. Covers base/overlay separation, patch strategy, resource references, naming conventions, generator options, and component reuse. Ensures Kustomize configurations are maintainable, DRY, and correctly structured.
Only triggers when kustomization.yaml is detected. Does not trigger for raw K8s manifests or Helm charts.
When to Use
- When reviewing Kustomize base/overlay structure
- When auditing patch strategy (strategic merge vs JSON patch)
- When checking resource references and overlay consistency
- When evaluating component reuse and overlay sprawl
When NOT to Use
- For raw K8s manifest review — use core K8s skills
- For Helm chart review — use
kubernetes-helm-review - When no
kustomization.yamlis found - For Kustomize runtime issues (build failures) — this is structural review only
Workflow
- Detect Kustomize: Confirm
kustomization.yamlexists at the target path. If not found, do not proceed. - Structure review: Map the base/overlay directory tree, identify all kustomization.yaml files.
- Base review: Check bases are generic and reusable, not environment-specific.
- Overlay review: Check overlays are minimal, environment-specific, and reference valid bases.
- Patch review: Evaluate patch strategy choices (strategic merge vs JSON patch).
- Resource reference check: Verify all referenced files exist, no orphaned patches.
- Naming conventions: Check namePrefix/nameSuffix consistency across overlays.
- Labels and annotations: Verify commonLabels and commonAnnotations used correctly.
- Generators: Check ConfigMap/Secret generators vs raw files.
- Component reuse: Identify duplicated config that should be extracted into components.
- Deprecation flag: If deprecated K8s API versions found in bases/overlays, flag and recommend
deprecation-check-and-upgrade. - Produce report: Present findings with check pass/fail status.
See check-tables.md for detailed check definitions.
Critical Checks
- Bases containing environment-specific values (should be in overlays)
- Overlays referencing non-existent bases or resources
- Patches targeting resources not in the base
- commonLabels that would break selector immutability on existing Deployments
- Secrets in plain text in generators without external secret references
Common Mistakes
| Mistake | Why It Happens | Correct Approach |
|---|---|---|
| Flagging strategic merge patches as always wrong | JSON patches are more precise but harder to read | Strategic merge is fine for simple field overrides; JSON patch for complex operations |
| Requiring components for every shared config | Components add indirection | Use components only when 3+ overlays share the same patch |
| Flagging namePrefix as inconsistency | Different envs may need different prefixes | Verify prefixes are intentional and documented |
| Treating all overlay differences as sprawl | Each environment needs specific config | Sprawl is when overlays differ in only 1-2 trivial values that could be parameterized |
| Not checking the rendered output | Kustomize YAML looks correct in parts but renders incorrectly | Run kustomize build mentally — do patches apply to the right targets? |
Supporting Files
check-tables.md— Overlay structure and patch checks with pass/fail criteria
Source: infraspecdev/tesseract — distributed by TomeVault.