Skip to main content
Just like other Kubernetes resource manifests, a kustomization.yaml file can include the apiVersion and kind fields. While Kustomize will infer sensible defaults when those fields are omitted, declaring them explicitly is a best practice. Explicit fields make your intent clear and reduce the chance of breakage when different Kustomize or kubectl versions are used.
Always specify apiVersion and kind in kustomization.yaml so your manifests remain explicit and portable across environments and Kustomize versions.

​
Common apiVersion / kind values

Which one to use depends on the Kustomize implementation and release you are targeting. Newer Kustomize versions provide the v1 group/version; older releases and some kubectl-bundled versions may default to v1beta1.

​
Example kustomization.yaml (explicit)

Including these fields is especially helpful when:
  • Sharing overlays or bases across teams and clusters.
  • Pinning manifests to a known Kustomize behavior.
  • Ensuring compatibility when switching between the standalone kustomize binary and the kubectl kustomize/kubectl apply -k built-in support.

​
Checking your Kustomize implementation

  • Standalone Kustomize binary:
  • If you rely on kubectl’s embedded Kustomize:
Then check the corresponding kubectl release notes to understand which Kustomize API versions it supports.

​
Compatibility guidance

  • Match the apiVersion in your kustomization.yaml to a version supported by your target Kustomize implementation.
  • If you use kubectl apply -k or kubectl kustomize, verify that your kubectl supports the Kustomize API version used in your manifest.
  • When upgrading Kustomize or kubectl, test overlays in a staging environment to detect any behavior changes between v1beta1 and v1.

​
Quick reference commands

Watch Video