Flux Schema

Flux Schema is a CLI for validating Kubernetes YAML manifests against JSON Schema and CEL rules using the same evaluation semantics as the Kubernetes API server. It ships as a single Go binary with a built-in catalog covering Kubernetes, OpenShift, Gateway API, and the Flux ecosystem CRDs.

This project is inspired by kubeconform, adding CEL rule evaluation, built-in schema extraction for CRDs & OpenAPI swagger, and a curated catalog refreshed automatically from upstream stable releases.

Features

• Strict schema validation — every field of every Kubernetes built-in kind and custom resource is checked. Unknown fields, wrong types, and missing required properties are all reported as schema violations.
• CEL evaluation — x-kubernetes-validations rules evaluated with the same engine as Kubernetes API server.
• Strict YAML decoding — duplicate keys are rejected matching Flux behavior. Metadata name, namespace, labels, and annotations are checked against API server rules (DNS-1123, qualified names).
• Built-in catalog — JSON Schemas with CEL rules for Kubernetes, OpenShift, Gateway API, Flux, Flagger, and Flux Operator CRDs, refreshed automatically against upstream.
• Custom catalogs — extract JSON Schemas from Kubernetes CRDs and OpenAPI swagger files, then layer your catalog on top of the default schemas.
• SOPS-aware — strip SOPS metadata fields so the rest of the document can be validated without decryption.
• Repository discovery — catalog a GitOps repository into a structured inventory designed for AI agents: directory classification, Flux resources with their defining files, and Kubernetes resource counts.
• Structured reports — versioned JSON or YAML validation reports for CI tooling and downstream automation.
• Declarative validation — define the validation config in a .fluxschema.yml file for reproducible runs across local and CI environments.
• GitHub Actions — composite actions for installation and manifests validation on GitHub runners.

Install

Install the plugin with the Flux CLI:

flux plugin install schema

For GitHub Actions runners, use the actions/setup action.

Quickstart

Validate a directory tree against the built-in catalog and 3rd-party schemas:

flux schema validate ./manifests \
--schema-location default \
--schema-location https://raw.githubusercontent.com/datreeio/CRDs-catalog/main

Build a kustomize overlay and validate the generated manifests:

kustomize build ./clusters/production | flux schema validate --verbose

Render a Helm chart and validate the generated manifests:

helm template ./charts/app | flux schema validate -v --skip-missing-schemas

Build a ResourceSet and validate the generated manifests:

flux operator build rset -f tenants.yaml | flux schema validate

Emit a structured report for CI tooling:

flux schema validate ./manifests -o json

Extract JSON Schemas from your CRDs and layer them on top of the built-in catalog:

kubectl get crds -o yaml | flux schema extract crd -d ./my-catalog

flux schema validate ./manifests \
  --schema-location ./my-catalog \
  --schema-location default