Flux – Flux CLI Plugins

Flux: Flux Mirror

Mon, 01 Jan 0001 00:00:00 +0000

Flux Mirror is a CLI for mirroring Helm charts, OCI artifacts and container images between registries using a declarative approach.

The intended use case is feeding an internal mirror registry that backs Flux OCIRepository and Kubernetes Deployments, so clusters never reach out to upstream registries at reconcile time.

It also enables migration away from HTTP/S HelmRepository sources: chart versions are republished as OCI Helm artifacts that HelmRelease consumes via an OCIRepository in spec.chartRef, dropping the runtime dependency on upstream chart repositories.

Features

OCI artifacts — mirror container images, OCI Helm charts, Flux OCI artifacts, and any other OCI-addressable artifact between registries. Manifests and blobs are copied byte-for-byte; multi-arch manifest lists are mirrored as a whole, no platform filtering.
Helm charts — mirror charts from HTTP/S Helm repositories to an OCI registries. Chart bytes are re-published as a deterministic Helm-OCI artifact, so drift detection on re-runs is content-based and stable.
OCI 1.1 referrers — opt-in mirror of signatures, SBOMs, and attestations attached to artifacts.
Cosign verification — opt-in keyless signature verification for selected source artifacts before they are mirrored, with optional minimum signature age.
Selector pipeline — for OCI artifacts, a four-step regex → semver → sort → top-N filter. For charts, a semver constraint plus top-N. Sort by semver, alphabetical, or numerical.
Idempotent — destination digests are compared per tag/version. Re-runs copy only what’s missing or drifted.
Drift gating — destination drift (different content under the same tag) is reported as a distinct outcome and exit code, so audit pipelines can differentiate “out of date” from “mutated tags”.
Registry auth — OCI auth supports Docker config and credential helpers, cloud workload identity for ECR/ACR/GAR, and per-host bearer credentials from GitHub/Forgejo OIDC, GCP, Azure, AWS STS, SPIFFE JWT-SVID, env vars, files, or JWK-signed JWTs. Per-host TLS/mTLS (custom CA, client cert, or SPIFFE X.509-SVID) is also supported. Helm HTTP/S credentials come from Helm’s repositories config.
Structured output — text and yaml/json for downstream tooling, plus a verbose mode that streams every blob and manifest digest for diagnosing TLS, auth, or push failures.

Install

Install the plugin with the Flux CLI:

flux plugin install mirror

Quickstart

Authenticate once against the destination and optionally source registries:

docker login ghcr.io

For private HTTP/S Helm repositories, login with Helm:

helm repo add private https://charts.example.com --username "$USER" --password "$TOKEN"

Write a config file describing what to mirror:

# flux-mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta1
kind: Config
charts:
 - name: external-dns
 source: https://kubernetes-sigs.github.io/external-dns/
 destination: oci://ghcr.io/my-org/charts
 version: "*"
 limit: 3
artifacts:
 - source: registry.k8s.io/external-dns/external-dns
 destination: ghcr.io/my-org/external-dns
 selector:
 semver: ">=0.15.0"
 limit: 3
 includeReferrers: true

Run the sync:

flux mirror sync flux-mirror.yaml

You can also read the config from stdin:

flux mirror sync - < flux-mirror.yaml

Preview without writing:

flux mirror sync flux-mirror.yaml --dry-run

Force a resync of drifted tags e.g. latest:

flux mirror sync flux-mirror.yaml --overwrite

See examples/ for more configurations and docs/sync.md for the full flag reference.

Flux: Flux Schema

Mon, 01 Jan 0001 00:00:00 +0000

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