Kustomize provides template-free customization of Kubernetes manifests — managing environment-specific variations (dev, staging, production) without duplicating entire YAML files. This guide covers the core workflow.
The Problem Kustomize Solves
Different environments typically need slightly different configuration (replica counts, resource limits, environment variables) from a common base — without a tool like Kustomize, teams often resort to duplicating entire manifest files with small variations, or complex templating that can be hard to reason about.
Kustomize's Approach: Base + Overlays
base/
deployment.yaml
service.yaml
kustomization.yaml
overlays/
production/
kustomization.yaml
replica-patch.yaml
staging/
kustomization.yamlA base configuration defines common resources; overlays apply environment-specific patches on top — no templating language, just structured patches to plain Kubernetes YAML.
Basic kustomization.yaml (Base)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yamlProduction Overlay with a Replica Patch
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patches:
- path: replica-patch.yamlapiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 5Production overrides the base's replica count (perhaps 1 or 2 in base/dev) to a production-appropriate 5, without duplicating the entire deployment definition.
Building and Applying with Kustomize
kubectl apply -k overlays/productionkubectl has built-in Kustomize support (-k flag) — no separate tool installation needed for basic usage.
Previewing Generated Output Before Applying
kubectl kustomize overlays/productionShows the fully-resolved manifest (base plus overlay patches applied) without actually applying it — useful for reviewing exactly what will be deployed before committing to the change.
Setting Environment-Specific ConfigMap Values
configMapGenerator:
- name: app-config
literals:
- API_URL=https://staging-api.yourdomain.comKustomize can generate ConfigMaps with environment-specific values directly, integrated into the overlay pattern rather than needing separate manual ConfigMap definitions per environment.
Adding Environment-Specific Labels
commonLabels:
environment: productionAutomatically applies consistent labeling across all resources in an overlay, useful for filtering/organizing resources by environment.
Combining with GitOps (ArgoCD)
See How to Set Up a Kubernetes CI/CD Pipeline with ArgoCD (GitOps) — ArgoCD has native Kustomize support, letting you point an ArgoCD Application directly at a Kustomize overlay path, combining both tools naturally.
Kustomize vs Helm
See How to Install and Use Helm: The Kubernetes Package Manager for comparison — Helm uses templating with a packaging/versioning model (charts); Kustomize uses patch-based customization of plain YAML without templating syntax; both are valid approaches, sometimes used together (Kustomize patching Helm-rendered output).
Common Errors
Patch doesn't seem to apply correctly — verify the patch's resource name/kind exactly matches the base resource it's meant to modify; Kustomize matches patches to base resources by name and kind, and a mismatch silently fails to apply as expected.
Continue Reading
- How to Install and Use Helm: The Kubernetes Package Manager
- How to Set Up a Kubernetes CI/CD Pipeline with ArgoCD (GitOps)
- How to Manage Multiple Environments (Dev/Staging/Prod) on a VPS
Browse more articles in Kubernetes & Container Orchestration.
