Skip to main content
Kustomize lets you manage Kubernetes manifests across multiple directories while keeping your repository layout organized and your apply workflow simple. This guide shows a practical example: start from a flat k8s/ folder and scale to a nested, maintainable Kustomize layout that’s CI/CD friendly. Why use Kustomize?
  • Avoid running kubectl apply in many directories.
  • Keep environment-specific overlays and common bases clean.
  • Aggregate resources with a single root kustomization.yaml.
Scenario
  • You have a k8s/ directory containing four YAML files:
    • api-depl.yaml (API Deployment)
    • api-service.yaml (API Service)
    • db-depl.yaml (DB Deployment)
    • db-service.yaml (DB Service)
Applying a flat directory If all four files live directly in k8s/, you can apply them with kubectl’s directory apply:
This is plain Kubernetes behavior and does not use Kustomize. Organizing into subdirectories As your manifests grow, you might split them into subdirectories:
  • k8s/api/ — contains api-depl.yaml, api-service.yaml
  • k8s/db/ — contains db-depl.yaml, db-service.yaml
Without Kustomize you’d run:
This approach works but becomes tedious as the number of directories increases—especially in CI/CD pipelines. Introduce a root kustomization.yaml Kustomize lets you declare a single root kustomization.yaml that references resources across directories or files. Create k8s/kustomization.yaml and list the relative paths to all manifests:
Note: paths in resources are relative to the directory containing that kustomization.yaml. Apply everything with one command You can render the combined manifests and apply them in two common ways:
  • Using the standalone Kustomize binary:
  • Or using kubectl’s embedded Kustomize renderer:
Example output (possible):
Scaling: nested kustomizations When you have many directories (for example: api, db, cache, kafka), listing every file in the root kustomization.yaml gets unwieldy. Instead, create a kustomization.yaml inside each subdirectory and reference the directories from the root. Example layout:
  • k8s/kustomization.yaml (root)
  • k8s/api/kustomization.yaml
  • k8s/db/kustomization.yaml
  • k8s/cache/kustomization.yaml
  • k8s/kafka/kustomization.yaml
Root kustomization.yaml:
Subdirectory kustomization.yaml (example: k8s/db/kustomization.yaml):
How it works
  • When Kustomize encounters a directory listed in resources, it looks for a kustomization file (for example kustomization.yaml or kustomization.yml) inside that directory.
  • It reads the listed resources in the subdirectory’s kustomization file and includes those manifests in the build.
  • The root kustomization.yaml therefore aggregates all subdirectory resources without needing to list each file individually.
Comparison: quick reference Best practices
  • Keep kustomization.yaml files close to the resources they reference.
  • Use directory-level kustomization.yaml files as logical units (service, database, cache).
  • Prefer kubectl apply -k in CI for simplicity unless you need Kustomize features not supported by kubectl’s embedded version.
You can use either kustomize build k8s/ | kubectl apply -f - or kubectl apply -k k8s/. kubectl apply -k is convenient because it uses the Kustomize renderer embedded in kubectl, which simplifies CI/CD steps.
Ensure a kustomization file (for example kustomization.yaml or kustomization.yml) exists in any directory you reference as a resource. Paths are interpreted relative to the containing kustomization.yaml. If a path points to a directory, that directory must contain a valid kustomization file.
Summary
  • Use a root kustomization.yaml to collect resources across directories.
  • For many directories, create a kustomization.yaml per subdirectory and reference directories from the root.
  • Apply all resources in one step using kustomize build piped to kubectl apply -f - or kubectl apply -k to simplify local workflows and CI/CD automation.
Links and references

Watch Video