Skip to content

Kubeconform: validate manifests before Kubernetes

Kubernetes · CI
Not studied

Added 2026-10-11. Requires Helm, Kubeconform and the Kubernetes version of the target environment.

Problem

Helm rendered the YAML successfully, but a Deployment says replica by mistake, or a string ended up in a numeric field. The error only shows up at apply time.

Solution

Kubeconform is "a Kubernetes manifest validation tool" — "incorporate it into your CI, or use it locally to validate your Kubernetes configuration". It validates manifests against the JSON Schema of the matching Kubernetes version and supports remote or local schema locations, which enables validating custom resources (CRDs) and offline validation. The -strict mode catches unknown fields and duplicate keys. Validate the Helm/Kustomize output, not just the source templates.

Example

Run from a repository with the chart in ./chart. Set K8S_VERSION explicitly, for example in a CI variable, to match the cluster version and an available schema; don't leave the default master.

#!/usr/bin/env bash
set -euo pipefail
: "${K8S_VERSION:?Set the target Kubernetes schema version, format X.Y.Z}"

mkdir -p build
helm template devops-kb ./chart \
  --kube-version "$K8S_VERSION" > build/rendered.yaml
test -s build/rendered.yaml
kubeconform -strict -summary \
  -kubernetes-version "$K8S_VERSION" build/rendered.yaml

Acceptance: resources were actually validated, with no Invalid, Errors or unexpected Skipped. Don't add -ignore-missing-schemas as a universal fix: that way the check may skip exactly your custom resources. For those, plug in the schemas of the right CRD version via -schema-location. For reproducible CI, pin the versions of the tool, the chart and the schema set.

Validation by the API server is a separate next step with an explicitly chosen context:

: "${KUBE_CONTEXT:?Set the test cluster context}"
kubectl --context "$KUBE_CONTEXT" apply \
  --dry-run=server -f build/rendered.yaml

A server-side dry run needs API access and checks rules that aren't in the JSON Schema, including admission. None of these checks prove that the Pod will start, the image will pull, or the application will handle the load.

When to use

In the CI of a Kubernetes repository before a GitOps merge. The current Docker Compose site doesn't need it; the card is for cluster work.

Source

How to apply it yourself

  1. Validate one chart with all the values in use, accounting for namespace and API versions.
  2. Add schemas for custom resources without blanket-skipping unknown types.
  3. In a test copy of the Deployment, replace replicas with replica; the check must fail.
  4. Keep the CI report and, once the check is mandatory, mark it "Studied".