Kustomize Validate: Lint Manifests Before Applying (2026)

Kustomize’s validate command lets you catch manifest errors before they hit your cluster, acting as a crucial pre-flight check for your Kubernetes configurations.

Imagine you’re about to deploy an application. You’ve got your Kustomize overlays ready, and you run kubectl apply -k ./my-app. Then, bam—you get a cryptic error from the Kubernetes API server: "error validating data: ValidationError(Pod.spec): unknown field 'foo' in type 'PodSpec'". Your deployment fails, and you’re left scrambling to figure out what went wrong. This is where kustomize validate shines. It simulates the API server’s validation process locally, using the same OpenAPI schemas that the API server uses, giving you immediate feedback without touching your cluster.

Let’s see it in action. Suppose you have a simple Kustomize setup:

./my-app/
  kustomization.yaml
  deployment.yaml

Your kustomization.yaml might look like this:

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

And deployment.yaml contains a standard Deployment resource:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

Now, let’s introduce an error. Imagine you mistakenly add an invalid field to the Deployment spec, like invalidField: "someValue".

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
  invalidField: "someValue" # <-- This is incorrect
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

If you were to run kubectl apply -k ./my-app now, you’d get an API server error. But with kustomize validate, you can catch this before applying:

kustomize validate ./my-app

The output would be something like:

deployment.yaml: error: Deployment.spec.invalidField: unknown field "invalidField"

This tells you exactly which file and which field caused the problem, allowing you to fix it immediately.

The kustomize validate command works by first building your Kustomize configuration into a set of raw Kubernetes manifests. Then, for each manifest, it consults the Kubernetes OpenAPI v3 schema that matches the API version of the resource. It then checks if the structure and fields present in your manifest conform to the schema. If there’s a mismatch—an unknown field, a missing required field, or a type mismatch—it reports an error. This is the same validation logic the Kubernetes API server uses when you kubectl apply.

The most surprising truth about Kustomize’s validation is that it doesn’t just check for basic YAML syntax errors. It performs deep semantic validation against the Kubernetes API’s own understanding of resources. This means it knows, for instance, that a Deployment object’s spec should not have a field named invalidField, or that a Pod’s containers array must contain at least one name. It leverages the very schemas that define Kubernetes itself to ensure your configurations are well-formed according to the API server’s expectations.

Beyond simply linting manifests, kustomize validate is critical for implementing GitOps workflows. By integrating this command into your CI/CD pipeline, you can prevent invalid configurations from ever reaching your Git repository, let alone being applied to your cluster. A typical CI step might look like:

# In your CI pipeline
echo "Validating Kubernetes manifests..."
kustomize build ./my-app | kubectl --server-dry-run=client -f -
if [ $? -ne 0 ]; then
  echo "Manifest validation failed!"
  exit 1
fi
echo "Manifest validation successful."

Here, kustomize build generates the final manifests, and then kubectl --server-dry-run=client -f - pipes these manifests to kubectl for a client-side dry run which invokes the server’s validation logic without actually sending the request to the API server. This is functionally very similar to what kustomize validate does, but demonstrates how you’d integrate it with existing kubectl dry-run capabilities. For a pure Kustomize approach, kustomize validate is the direct tool.

The kustomize validate command relies on having the correct Kubernetes OpenAPI schema files available locally. Kustomize typically downloads these schemas automatically when needed, but if you’re running in an air-gapped environment or encounter network issues, you might need to provide them manually. You can download the relevant schemas for your Kubernetes version from the official Kubernetes GitHub repository (e.g., https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/v3) and place them in a directory Kustomize can access.

The next step after ensuring your manifests are valid is to actually apply them.