Kustomize Large Repos: Speed Up Builds with Many Overlays (2026)

Kustomize builds can get painfully slow when your repo has hundreds or thousands of overlays.

Here’s how to speed that up.

The core problem is that kustomize build re-scans your entire directory tree for every single overlay, even if most of them share the same base. This leads to an exponential increase in I/O and CPU time as your overlay count grows.

Common Causes and Fixes

Unnecessary File Scanning: Kustomize walks the directory. If you have build artifacts, old logs, or large data files scattered throughout your overlay directories, Kustomize will try to process them.
- Diagnosis: Run du -sh /path/to/your/repo/overlays/* to see which directories are disproportionately large. Look for non-YAML/JSON files.
- Fix: Exclude these directories from Kustomize’s view. Use a .kustomizeignore file at the root of your repo.
```
# .kustomizeignore
build/
logs/
data/
*.log
```
- Why it works: .kustomizeignore tells Kustomize to skip specified files and directories entirely, reducing the amount of work it has to do to find valid resources.
Large Number of Base Files: If your overlays rely on a very large number of base files (e.g., hundreds of ConfigMaps, Deployments, etc.), Kustomize has to parse and merge all of them for each overlay.
- Diagnosis: Identify the resources or bases fields in your kustomization.yaml files. If these lists are extremely long, that’s a sign.
- Fix: Consolidate common resources into shared base directories. Create a common-bases directory with frequently used ConfigMaps, Secrets, etc., and include it in all overlays that need them.
```
# overlays/production/kustomization.yaml
resources:
- ../../common-bases
- ../../overlays/base
patchesStrategicMerge:
- deployment-patch.yaml
```
- Why it works: By referencing a single directory containing shared resources, Kustomize only needs to parse and process those common files once, rather than duplicating the effort for each overlay.
Deep Directory Structures: Extremely deep nesting of directories can also add overhead as Kustomize traverses the tree.
- Diagnosis: find /path/to/your/repo/overlays -type d | wc -l will tell you the total number of directories. If this number is in the thousands and the structure isn’t logically necessary, it’s a candidate.
- Fix: Flatten your overlay directory structure where possible. Group overlays by environment or application rather than creating deep, granular subdirectories for minor variations.
```
# Before
overlays/
├── prod/
│   ├── app1/
│   │   └── kustomization.yaml
│   └── app2/
│       └── kustomization.yaml
# After
overlays/
├── prod-app1/
│   └── kustomization.yaml
└── prod-app2/
    └── kustomization.yaml
```
- Why it works: A shallower directory structure reduces the number of directory traversal operations Kustomize needs to perform, leading to faster file discovery.
Inefficient Use of Patches: If you have many small, individual patch files for each overlay, Kustomize has to load and apply each one.
- Diagnosis: Count the number of files listed under patches or patchesStrategicMerge in your kustomization.yaml. If it’s hundreds, consider consolidating.
- Fix: Combine related patches into single files. For example, if you have deployment-replicas.yaml, deployment-image.yaml, and deployment-env.yaml, merge them into a single deployment-patches.yaml.
```
# overlays/staging/kustomization.yaml
patches:
- path: deployment-patches.yaml # Contains multiple strategic merges
```
- Why it works: Kustomize loads and parses patch files. Fewer files mean fewer I/O operations and less parsing overhead.
External Resources and Generators: If your Kustomize configuration relies on helmCharts or generators that themselves perform complex operations or fetch external data, this adds to build time.
- Diagnosis: Review your kustomization.yaml for helmCharts or generators sections. If these are complex or point to slow external sources, investigate them.
- Fix: Pre-render Helm charts or complex generators offline. Store the output YAML in your repository and reference it as a standard resource.
```
# overlays/dev/kustomization.yaml
resources:
- ../../charts/my-app-rendered.yaml # Pre-rendered output
```
- Why it works: By pre-computing the output of complex external operations, Kustomize’s job is reduced to simply including static YAML, which is much faster.
Large Number of Kustomization Files: Even if the content is simple, having tens of thousands of individual kustomization.yaml files can add up.
- Diagnosis: find /path/to/your/repo -name "kustomization.yaml" | wc -l will give you the count.
- Fix: Consolidate kustomizations. If multiple directories have identical or near-identical kustomization.yaml files, merge them. You can often have a single kustomization.yaml at a higher level that includes subdirectories.
```
# Before
app/
├── frontend/
│   └── kustomization.yaml
└── backend/
    └── kustomization.yaml
# After (if common base is desired)
app/
├── common/
│   └── kustomization.yaml # Shared resources
├── frontend/
│   └── kustomization.yaml # Includes ../common
└── backend/
    └── kustomization.yaml # Includes ../common
```
- Why it works: Reduces the number of kustomization.yaml files Kustomize needs to discover and parse during its initial scan.
Using kustomize build Directly in Loops: If you’re calling kustomize build in a shell loop over many overlays, the overhead of starting the Kustomize binary for each one is significant.
- Diagnosis: Look at your CI/CD pipeline scripts or shell scripts. Are you iterating and running kustomize build N times?
- Fix: Use a single kustomize build command that specifies multiple targets, or structure your build process to generate all necessary manifests in one go. Many CI systems allow you to parallelize or batch kustomize build calls. Alternatively, if you need to build specific overlays, list them explicitly in a single command: kustomize build overlay1 overlay2 overlay3.
- Why it works: Reduces process startup overhead and allows Kustomize to potentially optimize its scanning across multiple targets more effectively.

You’ll likely hit an error about exec.Command failing if your Kustomize build process itself is broken, but that’s a symptom, not the root cause of slow builds.