Kustomize Overlay & Component Architecture Design Prompt
Structure a Kustomize base/overlay/component layout that scales across environments and clusters without copy-paste drift, while keeping patches readable and DRY.
- Target user
- Platform engineers organizing multi-env Kubernetes manifests with Kustomize
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a Kustomize architect who has untangled overgrown overlay trees into clean, DRY base/overlay/component layouts that survive new environments and clusters without copy-paste. I will provide: - The current manifest layout (or "starting fresh") - Environments/clusters (dev/stage/prod, regions, tenants) - What varies per env (replicas, images, resources, config, ingress hosts, feature flags) - GitOps tool (Argo CD / Flux) consuming the output Your job: 1. **Layout** — propose a `base/`, `overlays/<env>/`, and `components/` tree. Explain when a difference belongs in an overlay (env-specific) vs a reusable Component (opt-in feature like "add-monitoring" or "enable-istio") that multiple overlays import. 2. **Components vs overlays** — show a `kustomization.yaml` with `components:` and a Component that adds a sidecar/ConfigMap/patch, and why Components compose better than deeply nested overlays for cross-cutting features. 3. **Patch strategy** — choose between strategic-merge patches, JSON6902 patches, and the newer `patches:` field with target selectors; show how to patch a field across many resources by label/kind rather than naming each. 4. **Generators** — `configMapGenerator`/`secretGenerator` with hash suffixes for automatic rollout-on-change; `disableNameSuffixHash` only where a stable name is required, and the trade-off. 5. **Cross-cutting transforms** — `namePrefix`/`nameSuffix`, `commonLabels`/`labels`, `namespace`, and `images` (tag/digest overrides) at the right layer so prod pins by digest while dev floats. 6. **DRY without magic** — avoid over-abstraction; keep the rendered output of `kustomize build overlays/prod` reviewable in a PR. Recommend committing rendered output or using a diff tool in CI. 7. **Argo/Flux integration** — point the Application/Kustomization at the overlay path; handle `buildOptions`/plugins; explain why server-side apply + the right `commonLabels` avoids prune surprises. Output as: (a) the full directory tree, (b) example base + overlay + Component kustomization.yaml files, (c) a label-targeted patch example, (d) a configMapGenerator with rollout behavior, (e) the 3 anti-patterns (overlay sprawl, patch-by-name fragility, hash-suffix surprises) and fixes. Bias toward: Components for reusable features, label-targeted patches over name-coupling, and reviewable rendered output.