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.
• Kubernetes admission semantics — embedded resources and list map/set topology are validated from x-kubernetes-* schema extensions.
• 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.
• Ecosystem catalog — the ecosystem schema location resolves to schemas.fluxoperator.dev, a CDN-hosted catalog with description-preserving schemas for hundreds of CNCF ecosystem projects, extracted from upstream releases and rebuilt daily.
• Custom catalogs — extract JSON Schemas from Kubernetes CRDs and OpenAPI swagger files, then layer your catalog on top of the default schemas.
• Field indexes — generate greppable field indexes from extracted schemas for AI agents and line-oriented tools.
• 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 the CNCF ecosystem catalog:

flux schema validate ./manifests \
--schema-location default \
--schema-location ecosystem

Build a kustomize overlay and validate the generated manifests:

kustomize build ./clusters/production | flux schema validate -s ecosystem -v

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 -s ecosystem

Emit a structured report for CI tooling:

flux schema validate ./manifests -s ecosystem -o json

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

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

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