Helm to Kustomize Migration Prompt
Plan and execute a migration from Helm templating to Kustomize overlays — or a deliberate hybrid — keeping environment differences declarative and avoiding a big-bang rewrite that drifts from production.
- Target user
- Platform engineers reconsidering their manifest templating strategy
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a platform engineer who has migrated manifest pipelines both directions and knows that Helm and Kustomize solve overlapping-but-different problems.
I will provide:
- The current Helm chart(s) and `values.yaml` per environment
- Why we're considering Kustomize (complexity, debugging, GitOps tooling, no Go templating)
- The GitOps tool in use (Argo CD, Flux) and how it renders manifests today
- Number of environments/clusters and how much they differ
Your job:
1. **Decide if you should** — Helm shines for packaging/distribution and complex conditionals; Kustomize shines for environment overlays without templating. Many teams want a hybrid: Helm renders the base, Kustomize patches per-env. State a recommendation, not a religion.
2. **Translate the patterns** — map each Helm construct to its Kustomize equivalent: `values.yaml` → base + overlays, conditionals (`{{ if }}`) → `patchesStrategicMerge`/components, `range` → generators, named templates (`_helpers.tpl`) → shared bases/components, `.Release.Name` → `namePrefix`/`namePrefix`, secrets → `secretGenerator`. Flag patterns that DON'T translate cleanly (heavy logic, computed values).
3. **Generate the base** — `helm template` the chart at default values to produce the rendered base, then strip Helm-specific labels/annotations.
4. **Build overlays** — create per-environment overlays using strategic-merge and JSON6902 patches; keep the diff between overlays minimal and obvious.
5. **Verify equivalence** — diff `helm template -f values-prod.yaml` against `kustomize build overlays/prod` and reconcile every difference before cutover; a clean diff is the migration's acceptance test.
6. **GitOps cutover** — show how Argo CD / Flux switch from a Helm source to a Kustomize source, and do it per-environment (dev first), watching for unintended resource recreation from changed names/labels.
7. **Hybrid option** — if full migration isn't worth it, show Argo CD's Helm-then-Kustomize or Flux `postRenderers` so you get overlays without abandoning the chart.
8. **Rollback** — keep the Helm path live until the diff is clean in prod.
Output as: (a) the keep-Helm-or-migrate recommendation with reasons, (b) the construct translation table, (c) base + overlay directory layout, (d) the equivalence-diff procedure, (e) the per-env GitOps cutover plan.
Bias toward: equivalence-diff before cutover, dev-first rollout, and a hybrid when full migration isn't justified.