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
| Option | What it does |
|---|---|
-strict | forbid fields not in the schema and duplicate keys in YAML |
-ignore-missing-schemas | skip resources without a schema (CRDs and others) (Skipped) instead of treating them as errors |
-skip Kind1,Kind2 | don't validate these kinds of resources (group/version/Kind allowed) |
-reject Kind1,Kind2 | forbid these kinds: their presence is an error |
-kubernetes-version 1.29.0 | which API version to validate against (substituted into the schema path) |
-schema-location path | where to look for schemas; can be repeated, with the {{ .ResourceKind }} template and others; default — the standard repository on GitHub |
-ignore-filename-pattern regex | skip files by path pattern; can be repeated |
Output
| Option | What it does |
|---|---|
-summary | at the end, a line Summary: N resources found in M files - Valid, Invalid, Errors, Skipped |
-verbose | also print valid resources (… is valid) |
-output text|json|tap|junit|pretty | format; json shows all errors of a resource, text only the first |
-exit-on-error | stop at the first error |
-n N | number of workers (default 4) |
-debug | which schema files are used |
-v | version |
Results and exit codes
| Status | Meaning |
|---|---|
valid | the resource matches the schema |
invalid | the 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 |
skipped | skipped 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;-strictadds the duplicate-key check; -kubernetes-versionhas no effect — the schema path is fixed;- for a kind missing from the directory (CRDs, the old
batch/v1beta1) you getcould not find schema— add-ignore-missing-schemasor-skip; - your own
-schema-locationis 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'sdataare the opposite, strings only:replicas: 3insidedatamust be written as"3". - YAML 1.1 turns
yes,no,on,off,y,ninto booleans.name: ybecomestrue, the keyn:becomesfalse, 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
-strictpasses silently: YAML takes the last value. With-strict—key "…" already set in map. - An empty file is
0 resources, code0. 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, code1), 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
kubeconformgoes to GitHub. Without internet access it fails withfailed downloading schema. You can download the schemas in advance and point to them with-schema-location.
See also
kubectl · yq · yamlschema · actionlint · gitlab-ci