Kustomize, when used with Git, isn’t just about managing YAML files; it’s about treating your entire application’s configuration as code that evolves alongside your application’s codebase.
Here’s a quick look at a typical workflow:
# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 1
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: my-repo/my-app:v1.0.0
ports:
- containerPort: 8080
# overlays/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patchesStrategicMerge:
- deployment-patch.yaml
# overlays/staging/deployment-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 2
template:
spec:
containers:
- name: my-app
image: my-repo/my-app:staging
Running kustomize build overlays/staging would output a Deployment with 2 replicas and the my-repo/my-app:staging image.
The core problem Kustomize solves is the duplication and drift of Kubernetes manifest files across different environments (dev, staging, prod) or configurations (e.g., different database backends). Instead of copying and modifying hundreds of YAML files, you define a common base configuration and then apply small, targeted patches or overlays for each environment. This ensures consistency and reduces the cognitive load of managing complex deployments.
Internally, Kustomize works by having a base directory containing your fundamental Kubernetes resources. Then, overlays directories define variations. Each overlay has its own kustomization.yaml file that points to the base resources and specifies any patches, transformers, or images that should be applied. When you run kustomize build, it merges these components, applying transformations without modifying the original base files. This is crucial for Git-based workflows because it means your base remains a single source of truth, and overlays are just deltas.
The real power comes from how this integrates with Git. You commit your base and overlays to a Git repository. Your CI/CD pipeline then checks out the repository, builds the specific overlay for the target environment (e.g., kustomize build overlays/production), and applies the resulting YAML to your Kubernetes cluster. When you need to update a configuration across all environments, you modify the base. When you need an environment-specific tweak, you modify the relevant overlay. Committing these changes to Git creates an auditable history of all configuration changes, tied directly to application deployments.
One thing most people don’t realize is that Kustomize’s patchesStrategicMerge is more powerful than simple YAML merging. It uses strategic merge patches, which means it can intelligently merge fields based on keys within the YAML structure. For instance, if you have a list of containers in a Deployment and your patch targets a specific container by name, Kustomize will merge the specifications for that specific container rather than just replacing the entire list. This allows for granular updates to complex nested structures without needing to re-declare everything.
This Git-driven Kustomize approach leads you naturally into managing application versions and rollbacks through Git tags and branches, making your infrastructure as versionable as your application code.