← Full reference

kubeconform

Validating Kubernetes manifests against JSON schemas without a cluster — strict, summary, CRDs, offline schemas

kubeconform validates Kubernetes YAML manifests against the API's JSON schemas: are the fields, types and nesting correct. No cluster is needed — it's a check of "how the API server would react to kubectl apply", handy to run in CI before a deploy. It doesn't check logic (whether selector and pod labels match, whether the image exists).

Syntax

kubeconform [options] file|directory… 
kubeconform [options] -          # manifests from stdin

One file may contain several documents separated by ---. A directory is walked recursively, picking up .yaml, .yml and .json.

Options

What counts as an error

OptionWhat it does
-strictforbid fields not in the schema and duplicate keys in YAML
-ignore-missing-schemasskip resources without a schema (CRDs and others) (Skipped) instead of treating them as errors
-skip Kind1,Kind2don't validate these kinds of resources (group/version/Kind allowed)
-reject Kind1,Kind2forbid these kinds: their presence is an error
-kubernetes-version 1.29.0which API version to validate against (substituted into the schema path)
-schema-location pathwhere to look for schemas; can be repeated, with the {{ .ResourceKind }} template and others; default — the standard repository on GitHub
-ignore-filename-pattern regexskip files by path pattern; can be repeated

Output

OptionWhat it does
-summaryat the end, a line Summary: N resources found in M files - Valid, Invalid, Errors, Skipped
-verbosealso print valid resources (… is valid)
-output text|json|tap|junit|prettyformat; json shows all errors of a resource, text only the first
-exit-on-errorstop at the first error
-n Nnumber of workers (default 4)
-debugwhich schema files are used
-vversion

Results and exit codes

StatusMeaning
validthe resource matches the schema
invalidthe schema was found, the resource doesn't match it: an extra field, wrong type, missing required field
error (failed validation)couldn't validate: YAML doesn't parse, no kind, no schema, a rejected kind
skippedskipped via -skip or -ignore-missing-schemas

Exit code 0 — no invalid and no error; 1 — at least one.

Without -summary and -verbose, on success kubeconform prints nothing — look at the exit code.

How it's set up in the IzzyLab sandbox

The sandbox has no internet access, while the regular kubeconform downloads schemas from GitHub. So kubeconform here is a wrapper that adds -schema-location '/opt/k8s-schemas/{{ .ResourceKind }}{{ .KindSuffix }}.json'. /opt/k8s-schemas holds Kubernetes 1.32 schemas for common kinds: Deployment, Service, ConfigMap, Secret, Pod, Job, CronJob, Ingress, StatefulSet, DaemonSet, HPA, NetworkPolicy, PVC, RBAC and others (ls /opt/k8s-schemas).

Specifics:

  • the schemas are the strict variant — extra fields are forbidden even without -strict; -strict adds the duplicate-key check;
  • -kubernetes-version has no effect — the schema path is fixed;
  • for a kind missing from the directory (CRDs, the old batch/v1beta1) you get could not find schema — add -ignore-missing-schemas or -skip;
  • your own -schema-location is honored too — after the built-in one.

Examples

cat > app.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      containers:
        - name: web
          image: nginx:1.27
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector: {app: web}
  ports:
    - port: 80
EOF

# strict validation with a summary — a typical CI step
kubeconform -strict -summary app.yaml

# a whole directory of manifests, every resource in the output
kubeconform -strict -summary -verbose k8s/

# generated manifests — straight from a pipeline
kubectl create deployment demo --image=nginx --dry-run=client -o yaml | kubeconform -strict -summary -

# the manifests contain CRDs with no schemas
kubeconform -strict -ignore-missing-schemas -summary k8s/

# don't validate specific kinds, reject others
kubeconform -skip Certificate -reject Secret -summary k8s/

# all errors of a resource (text shows only the first)
kubeconform -strict -output json app.yaml

# skip Helm templates and kustomize patches
kubeconform -summary -ignore-filename-pattern 'templates/' -ignore-filename-pattern 'patch' k8s/

# in CI: fail if anything is wrong
kubeconform -strict -summary k8s/ || exit 1

Reading errors

typo.yaml - Service web is invalid: problem validating schema. Check JSON formatting:
  jsonschema: '/spec/ports/0/port' does not validate with
  file:///opt/k8s-schemas/service-v1.json#/properties/spec/.../port/type: expected integer, but got string
  • typo.yaml - Service web — the file, kind and name of the resource;
  • '/spec/ports/0/port' — the path to the field: spec.ports[0].port;
  • at the end — the gist: expected integer, but got string, additionalProperties 'selectr' not allowed (a typo or extra field), missing properties: 'containers' (a required field is missing).

The phrase Check JSON formatting is boilerplate and usually has nothing to do with JSON formatting.

Pitfalls

  • Numbers and strings. port: "80" is an error (a number is required), while values in a ConfigMap's data are the opposite, strings only: replicas: 3 inside data must be written as "3".
  • YAML 1.1 turns yes, no, on, off, y, n into booleans. name: y becomes true, the key n: becomes false, and the error will be about a strange field. Quote such values.
  • Text output shows only a resource's first error. Fix one and the next one appears. To see them all at once, use -output json.
  • A duplicate key without -strict passes silently: YAML takes the last value. With -strict — key "…" already set in map.
  • An empty file is 0 resources, code 0. If you mistype the path to a generated file or the pipeline outputs nothing, the check "passes". Look at -summary: how many resources were found.
  • A missing file is an error (lstat …: no such file or directory, code 1), but an empty directory isn't.
  • Valid ≠ working. A selector that doesn't match the pod labels, a nonexistent image or ConfigMap — all of these pass schema validation.
  • Without offline schemas the standard kubeconform goes to GitHub. Without internet access it fails with failed downloading schema. You can download the schemas in advance and point to them with -schema-location.

See also

kubectl · yq · yamlschema · actionlint · gitlab-ci