> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kustomize Problem Statement and Ideology
> Explains using Kustomize to manage Kubernetes manifests by keeping a base and environment overlays to avoid duplicated YAML and simplify environment-specific changes
Before we explain what Kustomize is and how to use it, let's examine the real problem Kustomize was designed to solve and the design choices behind it.
Consider a minimal NGINX Deployment that creates a single pod:
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 1
selector:
matchLabels:
component: nginx
template:
metadata:
labels:
component: nginx
spec:
containers:
- name: nginx
image: nginx
```
Now imagine you manage multiple environments — `dev` (local), `stg` (staging), and `prod` (production) — with environment-specific behavior such as different replica counts:
| Environment | Replica count |
| - | - |
| dev | 1 |
| stg | 2 |
| prod | 5 |
A naive approach is to copy the same YAML files into each environment directory and update only the environment-specific values (like `replicas`) in each copy.
For example, you might duplicate the Deployment for each environment and run:
```bash theme={null}
# Apply development environment manifests
$ kubectl apply -f dev/
deployment.apps/nginx-deployment created
# Apply staging environment manifests
$ kubectl apply -f stg/
deployment.apps/nginx-deployment created
```
This "copy and edit" method works initially but quickly becomes unmanageable. As you add more resources (Services, ConfigMaps, Secrets, additional Deployments, etc.), you must remember to copy each new or changed manifest into every environment folder. Missing a copy or forgetting to synchronize changes causes drift and inconsistent environments.
Kustomize addresses this duplication problem with a simple, declarative approach: keep one canonical set of manifests (the base) and express only environment-specific changes (overlays). Because Kustomize operates on plain YAML and uses non-templated patches, manifests stay readable and compatible with standard YAML tooling (linters, validators, CI/CD pipelines).
Core concepts
| Term | Meaning |
| - | - |
| Base | YAML resources that are common across environments — the canonical default manifests. |
| Overlay | A set of files describing only the differences to apply to the base for a specific environment. |
Example — base (shared) NGINX Deployment:
```yaml theme={null}
# base/nginx-depl.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 1
selector:
matchLabels:
component: nginx
template:
metadata:
labels:
component: nginx
spec:
containers:
- name: nginx
image: nginx
```
Because the base defines `replicas: 1`, the `dev` environment typically needs no replica override. For `stg` and `prod` we create small overlay patches that adjust only the replica count.
Staging overlay patch:
```yaml theme={null}
# overlays/stg/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 2
```
Production overlay patch:
```yaml theme={null}
# overlays/prod/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 5
```
Each overlay requires a `kustomization.yaml` that references the base and the patch. For example, the staging overlay's `kustomization.yaml`:
```yaml theme={null}
# overlays/stg/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patchesStrategicMerge:
- replicas-patch.yaml
```
When you run Kustomize (or `kubectl apply -k`), Kustomize:
* Loads the base resources,
* Applies the overlay patches/transformations,
* Produces the final manifests for that environment.
You never duplicate full manifests for every environment — you express only what changes.
Repository layout (common pattern)
```text theme={null}
k8s/
├─ base/
│ ├─ kustomization.yaml
│ ├─ nginx-depl.yaml
│ ├─ service.yaml
│ └─ redis-depl.yaml
└─ overlays/
├─ dev/
│ ├─ kustomization.yaml
│ └─ config-map.yaml
├─ stg/
│ ├─ kustomization.yaml
│ └─ config-map.yaml
└─ prod/
├─ kustomization.yaml
└─ config-map.yaml
```
Workflow summary
* Put shared manifests in `base/`.
* Create one overlay folder per environment under `overlays/`.
* In each overlay, reference the base and include only the patches/overrides and environment-specific resources.
* Build and apply environment manifests with Kustomize or `kubectl apply -k overlays/` (use backticks for angle brackets).
Kustomize is integrated into `kubectl` (you can use `kubectl kustomize` or `kubectl apply -k`), but the embedded Kustomize version in `kubectl` may lag behind the standalone Kustomize release. If you require the latest Kustomize features, consider installing the standalone Kustomize CLI.
Kustomize operates on plain YAML without introducing templating syntax. Define base resources as regular YAML and describe overlays as YAML patches — there is no templating language to learn, unlike Helm.
The Kustomize version bundled into `kubectl` may not include the newest features or flags. If you depend on recent Kustomize functionality, install the standalone CLI from the official [Kustomize releases](https://github.com/kubernetes-sigs/kustomize/releases) or follow the project documentation.
Kustomize is intentionally simple: reuse common manifests, declare only the differences per environment, and keep everything as plain, valid YAML. For more details, see the [Kustomize documentation](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/) and the official [Kubernetes documentation](https://kubernetes.io/docs/).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.