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.

• 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 the plugin with the Flux CLI:

flux plugin install schema

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

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

Running Flux Schema in CI shifts validation left, so schema violations are caught in pull requests rather than on the cluster after Flux reconciles them. The CLI ships as GitHub Actions for repositories hosted on GitHub, and as a multi-arch (AMD64 and ARM64) container image for other CI systems and air-gapped environments.

Two composite actions cover GitOps validation pipelines:

• fluxcd/flux-schema/actions/setup — install the CLI on GitHub runners.
• fluxcd/flux-schema/actions/validate — auto-detect kustomize overlays, render them with kubectl kustomize, and validate every YAML document against the catalog (including CEL rules). Configurable via .fluxschema.yml.

Minimal pull-request workflow:

name: flux-schema

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Setup Flux Schema CLI
        uses: fluxcd/flux-schema/actions/setup@main
      - name: Validate manifests
        uses: fluxcd/flux-schema/actions/validate@main

The ghcr.io/fluxcd/flux-schema image bakes the built-in catalog into /catalog/latest/, so it can validate manifests in air-gapped environments:

docker run --rm \
  -v "$PWD/manifests:/manifests:ro" \
  ghcr.io/fluxcd/flux-schema:latest validate /manifests \
  --schema-location /catalog/latest

See the Docker section of the validation guide for details on running the CLI in CI using the container image.

Run flux schema <command> --help for the full flag list.

• Manifest validation guide — flag reference, schema resolution, CEL rules, skipping documents and fields, and config files.
• Custom catalog guide — populate, layout, host, and refresh your own catalog with the extract commands.
• Repository discovery guide — catalog a GitOps repository with the discover command.
• Validation report reference — envelope shape and JSON Schema for -o json / -o yaml output.
• Inventory reference — envelope shape and JSON Schema for the discover command output.
• Configuration reference — config file envelope and JSON Schema for --config.
• Built-in catalog — Kubernetes, OpenShift, Gateway API, and Flux ecosystem CRDs covered by the default default schema location.

The Flux Schema project is Apache 2.0 licensed and accepts contributions via GitHub pull requests.