kustomization.yaml: The Kustomize Config File
kustomization.yaml declares the resources, transformers, and generators that kustomize build assembles into final manifests.
Every Kustomize directory is anchored by a kustomization.yaml. Knowing its top-level fields and exact spelling avoids most build failures.
What it does
kustomization.yaml is a YAML document with apiVersion kustomize.config.k8s.io/v1beta1 and kind Kustomization. It lists inputs (resources, components) and the transformers and generators applied to them. kustomize build reads it and emits combined manifests on stdout.
Common usage
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: web
namePrefix: prod-
resources:
- deployment.yaml
- service.yaml
images:
- name: myapp
newTag: 1.4.2Top-level fields
| Field | What it does |
|---|---|
| apiVersion / kind | kustomize.config.k8s.io/v1beta1 and Kustomization |
| resources | Files or directories to include |
| components | Reusable Kustomization Components to apply |
| namespace / namePrefix / nameSuffix | Namespace and name transformers |
| images | Override image names and tags |
| patches | Strategic-merge or JSON 6902 patches |
| configMapGenerator / secretGenerator | Generate ConfigMaps and Secrets |
In CI
Always set apiVersion and kind explicitly so newer kustomize versions do not warn or default unexpectedly. Render with kustomize build into an artifact and apply that, so the same bytes that passed review reach the cluster.
Common errors in CI
A newer kustomize rejecting an old key with "json: unknown field \"patchesStrategicMerge\"" means the field was deprecated in favor of patches. "kind: should be Kustomization but got <X>" means a typo. "accumulating resources: missing metadata.name" means a listed resource is not valid YAML.