Kubeconform — Fast Kubernetes Manifest Validation Against Upstream Schemas

Introduction

Kubeconform is a Kubernetes manifest validator that checks YAML files against the official Kubernetes OpenAPI schemas. It was created as a faster, actively maintained replacement for kubeval, with support for custom resource definitions (CRDs) and configurable schema sources.

What Kubeconform Does

• Validates Kubernetes YAML and JSON manifests against the official OpenAPI schema for a target K8s version
• Detects unknown fields, missing required properties, and type mismatches
• Supports CRD validation by loading schemas from custom registries or local directories
• Processes files from disk, stdin, or piped from tools like Helm and Kustomize
• Runs in strict mode to reject any fields not defined in the schema

Architecture Overview

Kubeconform is a single Go binary that downloads and caches JSON schemas from configurable registries (by default, the yannh/kubernetes-json-schema GitHub repository). For each input document it extracts the apiVersion and kind, looks up the matching schema, and runs JSON Schema validation. Schema resolution supports multiple registries in priority order, enabling CRD schemas to be served alongside built-in Kubernetes types.

Self-Hosting & Configuration

• Zero dependencies: single static binary for Linux, macOS, and Windows
• Schemas are cached locally after first download in a configurable cache directory
• -schema-location flag points to custom schema registries for CRDs (HTTP URLs or local paths)
• -kubernetes-version pins validation to a specific K8s API version
• Integrates into CI with -output json or -output junit for structured reporting

Key Features

• Significantly faster than kubeval (5-10x in benchmarks) due to concurrent file processing
• Built-in support for CRD validation via pluggable schema registries
• Strict mode catches unknown or deprecated fields that would otherwise be silently accepted
• Multi-document YAML support processes files with multiple resources separated by ---
• Exit codes distinguish between validation failures and processing errors for CI gating

Comparison with Similar Tools

• kubeval — The original Kubernetes manifest validator; Kubeconform is a faster, maintained successor with CRD support
• KubeLinter — Checks best practices and security policies; Kubeconform validates schema correctness
• Polaris — Focuses on configuration best practices; does not perform schema validation
• Pluto — Detects deprecated API versions; Kubeconform validates full schema compliance
• kubectl --dry-run=server — Server-side validation requires a running cluster; Kubeconform works offline

FAQ

Q: How is Kubeconform different from kubeval? A: Kubeconform is faster, supports CRD schemas via custom registries, handles multi-document YAML, and is actively maintained. kubeval is no longer updated.

Q: Can Kubeconform validate Helm charts? A: Pipe rendered templates: helm template mychart | kubeconform -summary. This validates the final YAML output after template rendering.

Q: How do I add CRD schemas? A: Host CRD JSON schemas in a registry following the expected directory structure, then pass -schema-location pointing to that registry. The datree/CRDs-catalog project provides schemas for popular CRDs.

Q: Does strict mode reject Helm annotations and labels? A: No. Standard metadata fields (annotations, labels) are part of the Kubernetes schema. Strict mode rejects fields not defined in the resource's spec, such as typos in container fields.

Sources

• https://github.com/yannh/kubeconform
• https://github.com/yannh/kubernetes-json-schema