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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes