kustomize

Best Practices

• Use a base/ directory for shared resources and overlays/ for environment variants
• Prefer strategic merge patches over full resource replacement
• Use commonLabels and commonAnnotations in kustomization.yaml for consistency
• Use ConfigMapGenerator and SecretGenerator instead of raw ConfigMap/Secret resources
• Set namespace in overlay kustomization.yaml, not in individual resources
• Pin image tags using the images transformer rather than patching deployment specs
• Use components for cross-cutting concerns shared between overlays (monitoring sidecars, etc.)
• Keep patches small and focused on a single concern
• Use namePrefix or nameSuffix to distinguish resources across environments
• Reference resources by relative path in kustomization.yaml
• Validate output with kubectl kustomize before applying
• Use replacements (Kustomize 5+) instead of deprecated vars for value substitution

Documentation Sources