Kustomize ApiVersion and Kind

A kustomization.yaml file, like any other Kubernetes manifest, can include the apiVersion and kind fields. These fields are optional because Kustomize and kubectl will infer sensible defaults when they are omitted, but explicitly declaring them improves clarity, portability, and compatibility across different Kustomize or kubectl versions. Example — typical minimal kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

Why you should set these fields

apiVersion: Identifies the Kustomize API schema used to interpret the file. Kustomize evolves over time; different releases may add fields or change behavior. Explicitly setting apiVersion ensures the file is validated and processed using the intended schema.
kind: For kustomization files, this value is always Kustomization. Including it removes any ambiguity when tooling inspects the manifest.

Table — quick reference

Field	Purpose	Example
`apiVersion`	Kustomize API schema used to parse and validate the kustomization file.	`kustomize.config.k8s.io/v1beta1`
`kind`	Identifies this manifest as a kustomization.	`Kustomization`
`resources`	List of resource files or directories included in the kustomization.	`- deployment.yaml`

When to include or update apiVersion

Include apiVersion for robust, version-stable manifests that work across different environments and CI/CD pipelines.
If you upgrade Kustomize (or your kubectl version that bundles Kustomize) and the new release introduces a new API (for example v1), update apiVersion in your kustomization files as part of the upgrade process.
If you get errors about unknown fields or unsupported API, confirm the Kustomize version you are using and match the apiVersion accordingly.

Example — minimal kustomization (repeated for clarity):

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

Always match apiVersion to the Kustomize/library version your tooling expects (for example, kustomize.config.k8s.io/v1beta1 or later). When upgrading Kustomize, verify whether the release introduces a new API (v1, etc.) and update your kustomization.yaml files to maintain compatibility.

Common commands

Render resources locally using the Kustomize CLI:

kustomize build ./path/to/overlay

Apply a kustomization directory with kubectl:

kubectl apply -k ./path/to/overlay

If you see errors such as “unknown field” or “unsupported apiVersion”, check the Kustomize version bundled with your kubectl or the standalone Kustomize binary. Update the apiVersion in your kustomization.yaml or align tooling versions to resolve schema mismatches.

Links and references

Kustomize documentation: https://kubectl.docs.kubernetes.io/references/kustomize/
Kubernetes kustomize guide: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/
kubectl reference: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands

If you need an example of upgrading apiVersion between Kustomize releases or help detecting the Kustomize version in your environment, I can provide step-by-step guidance.

Introduction

Core Concepts

Configuration

Multi-Container Pods

Observability

POD Design

State Persistence

Certification Tips

Helm Fundamentals

(2025 Updates) Kustomize Basics

Lightning Labs

Mock Exams

Security

Services & Networking

Kustomize ApiVersion and Kind

Watch Video