kubeconform: fast Kubernetes manifest validation that covers your CRDs

The gap kubeconform fills between kubectl apply and your editor

A typo in a Deployment field, a string where an integer belongs, or a key that no longer exists in the API version you target will surface at apply time, often after a merge and sometimes in the wrong cluster. kubeconform moves that check earlier. It reads YAML (or JSON) manifests from files or directories and validates each document against JSON schemas derived from the Kubernetes OpenAPI specification. The project is explicit that it is inspired by, contains code from, and is designed to stay close to Kubeval, so anyone already running Kubeval in CI will recognise the model immediately. The intended audience is the person who owns the manifests, not the cluster: platform engineers writing Helm charts, teams with a GitOps repository full of raw YAML, and anyone who wants a validation step that runs without a live API server. The README frames it as something to incorporate into CI or run locally, and both uses are the same binary with the same flags.

How kubeconform resolves a schema and what it actually checks

The mechanism is schema lookup by apiVersion and kind. Kubernetes' API is described with the OpenAPI specification in a file checked into the main Kubernetes repository, and because the tooling for validating against OpenAPI directly is awkward, projects convert that file into JSON schemas first. kubeconform depends on a self-updating fork of the kubernetes-json-schema project, which the README describes as more meticulously kept up to date and containing schemas for all recent Kubernetes versions. When you point it at a manifest, it identifies the resource, fetches the matching schema, and validates the document against it. Downloads run over multiple goroutines and downloaded files are cached in memory, which is the basis for the speed claim in the README's comparison against Kubeval. The -kubernetes-version flag selects which version of Kubernetes you validate against, defaulting to master, so a manifest targeting 1.29 can be checked against 1.29 rather than whatever the tool assumes. Two flags change the strictness of the check: -strict disallows additional properties not in the schema and duplicated keys, while the default tolerates them. That difference matters in practice, since Helm output frequently carries extra annotations that a strict run would reject. Schema locations are configurable through -schema-location, which can be passed more than once, and that is the hook that makes custom resources and offline validation possible.

Installing kubeconform and validating your first manifest

On macOS or Linux with Homebrew, the README gives a one-line install. On Windows it documents winget, and there is a release page plus a Go install path for anyone who prefers to build from source.

brew install kubeconform

If you have Go available, the README shows both a pinned version and the latest tag. Pinning is the safer habit for CI, since the schema registry and the binary can move independently.

go install github.com/yannh/kubeconform/cmd/[email protected]

After installation, point it at a file or a folder. A valid manifest produces no output and exit code 0, which is exactly what a CI step wants.

kubeconform fixtures/valid.yaml
echo $?

For a repository-wide check, the README's own speed example passes directories and asks for a summary, with -ignore-missing-schemas so that resources without a schema are skipped rather than failing the run. The -n flag sets the number of concurrent goroutines, four by default.

kubeconform -ignore-missing-schemas -n 8 -summary preview staging production

The output format is selectable with -output, which accepts json, junit, pretty, tap and text, defaulting to text. junit and tap are the two formats intended for CI systems that parse test results, and the README notes that -summary is ignored for junit output while -verbose is ignored for tap and junit.

Custom resources, OpenShift schemas and offline runs

The default schema source only knows about built-in Kubernetes kinds, which is where most validators stop. kubeconform lets you override the schema location search path with -schema-location, repeatable, so you can point at a local directory of JSON schemas or at a remote base URL. The README documents CustomResourceDefinition support and OpenShift schema support as the two worked cases. For a CRD, the practical route is to generate or vendor JSON schemas for your custom kinds and pass their location; for OpenShift, you point at the OpenShift schema set instead of the upstream one. Offline validation falls out of the same flag: if the schemas are on disk, no network call is needed, and the -cache flag lets you keep HTTP-downloaded schemas in a folder between runs. The -insecure-skip-tls-verify flag exists for environments with interception proxies, and the README has a dedicated proxy support section. Two filters shape what gets checked at all: -skip takes a comma-separated list of kinds or GVKs to ignore, and -reject takes a list to fail on. The distinction is useful when a repository contains both resources you own and resources you only pass through.

Where kubeconform stops short

The README is unusually direct about the limits, and it is worth taking at face value. kubeconform, like Kubeval, validates manifests only against the official Kubernetes OpenAPI specifications. Kubernetes controllers perform additional server-side validations that are not part of those specifications, and kubeconform does not cover them. The README cites issues #65, #122 and #142 as examples and recommends a third-party tool or kubectl --dry-run=server to fill the gap. So a manifest can pass kubeconform and still be rejected by the API server, and no amount of strictness changes that, because -strict only affects additional-properties and duplicate-key handling within the schema. The second limitation is schema coverage. If a kind has no schema at the location you configured, the run fails unless you pass -ignore-missing-schemas, which converts a hard failure into a silent skip. In a CI pipeline that flag is convenient and also a blind spot: a CRD whose schema quietly disappeared from your schema directory will not fail the build. Treat the skip count in the -summary output as something to read, not just the valid count. Finally, kubeconform is not an admission webhook and not a policy engine. It has no opinion about whether a container should run as root or whether a registry is allowed; it answers a narrower question about whether the document matches a schema.

kubeconform vs kubeval and the rest of the validation stack

The nearest comparison is Kubeval, and the README makes the case directly: kubeconform is a faster tool with configurable remote or local schema locations, which is what enables CRD and offline validation, and it defaults to a self-updating fork of the schema registry rather than the instrumenta one. The speed section in the README shows a run over preview, staging and production with the -summary flag completing in seconds where the equivalent kubeval invocation took longer, on the same machine. That is the project's own comparison, not an independent benchmark, and the gap is largely explained by concurrency and in-memory caching rather than by a different validation strategy. The other tools in this space answer different questions. helm lint checks chart structure and templating conventions rather than the rendered object against the Kubernetes API schema, so the two are complementary: lint the chart, then validate the rendered output. kubectl --dry-run=server talks to a real API server and therefore covers the server-side validation kubeconform cannot, at the cost of needing credentials and a reachable cluster. If your requirement is offline validation of a GitOps repository with custom resources, kubeconform is the closest fit of the three; if your requirement is policy enforcement, none of them is.

Maintenance, licence and the cost of keeping schemas current

kubeconform is Apache-2.0 licensed, which the Dockerfile also states in its org.opencontainers.image.licenses label. The repository is not archived, and the last push was on 2026-06-13. Releases arrive when they arrive: v0.8.0 on 2026-06-04, v0.7.0 on 2025-05-12, and v0.6.7 on 2024-07-30 before that, so plan for roughly annual major tags rather than a steady stream. The upgrade cost is low because the interface is a single binary with flags, and the Go module path github.com/yannh/kubeconform/pkg/validator is importable if you want to embed validation rather than shell out; go.mod shows Go 1.26 and vendored dependencies, so building from source pulls nothing at build time. The real ongoing cost is not the binary, it is the schemas. The default source is a self-updating fork, so new Kubernetes versions arrive without you doing anything, but the moment you override -schema-location to cover your CRDs you own the freshness of those files. A CRD schema that lags behind the CRD's served version will validate against the wrong shape. If you use -cache, decide whether the cache directory is a CI artifact or a checked-in directory, because a stale cache is another way for the check to drift from reality. On licensing: Apache-2.0 permits commercial and internal use and includes a patent grant, but the schema data you point at may come from elsewhere with its own terms, and that is worth a look before you vendor a schema directory into a product. This is a description of the licence, not legal advice.

Editorial conclusion

Adopt kubeconform if your pipeline produces YAML that never touches a cluster until deploy time, or if you need offline or CRD-aware validation on a laptop. Do not treat a clean exit as proof the API server will accept the object: the README states the controllers perform additional server-side validations outside the OpenAPI specifications, and points to kubectl --dry-run=server for that gap. Before wiring it in, check that the schema source you intend to use (the default self-updating fork of kubernetes-json-schema, or your own -schema-location) actually carries the Kubernetes versions and CRDs you ship, and pin that choice in your CI config rather than relying on defaults.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. yannh/kubeconform on GitHub