CLI tool for building, diffing, and validating Flux GitOps resources locally. Works with a local git repository — no cluster connection required. All tools (git, kustomize, helm) are embedded via Go SDK; no external binaries needed.
go install github.com/banschikovde/fluxview/cmd/fluxview@latestor via Docker:
docker run --rm -v $(pwd):/repo -w /repo ghcr.io/banschikovde/fluxview:latest \
diff ks --path clusters/prod/flux/ --branch-orig master- build — assemble Kustomization and HelmRelease resources
- diff — per-resource comparison against a git revision
- validate — schema validation via the kubeconform engine: native Kubernetes kinds out of the box, Flux/custom CRD schemas via
--schema-dir; supports--strict,--skip-kind,--output json|junit - inventory — a table of all software the GitOps repository deploys (Helm releases, plain-manifest workloads, operator CRs, CRDs) with versions;
tableor GFMmarkdownoutput, MR-ready change summary via--branch-orig - Recursive Kustomization discovery following
spec.pathinto shared bases (Flux controller behavior) - postBuild variable substitution from ConfigMaps and Secrets (Secret values redacted with a placeholder)
- On-disk caching of Helm charts, remote resources, and kustomize builds — warm runs make no network requests and skip kustomize entirely (details)
- Automatic secret redaction
- Box-header output format (per-resource, sorted by kind/namespace/name)
Resource types accept the full name as well as the short alias: kustomization = ks, helmrelease = hr.
Both build ks and build hr require Flux Kustomization files in --path (same contract).
# Build all Kustomizations (kustomize output: Flux CRs, HelmRelease, OCIRepository, etc.)
fluxview build ks --path clusters/prod/flux/
# Filter by namespace
fluxview build ks --path clusters/prod/flux/ --namespace cert-manager
# Without CRDs and noisy metadata
fluxview build ks --path clusters/prod/flux/ --skip-crds --strip-attrs status,creationTimestamp
# Inflate all HelmReleases (renders Helm chart templates) / a specific one
fluxview build hr --path clusters/prod/flux/
fluxview build hr podinfo --path clusters/prod/flux/Output uses per-resource box headers (same format as diff):
----------------------------------------
HelmRelease: cert-manager/cert-manager
----------------------------------------
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
...
# Diff all Kustomizations / HelmReleases against master
fluxview diff ks --path clusters/prod/flux/ --branch-orig master
fluxview diff hr --path clusters/prod/flux/ --branch-orig master
# Only resources in flux-system namespace
fluxview diff ks --path clusters/prod/flux/ --branch-orig master --namespace flux-system
# Tuning: strip noisy attrs, skip CRDs, wider diff context
fluxview diff ks --path clusters/prod/flux/ --branch-orig master \
--strip-attrs helm.sh/chart,checksum/cm,status --skip-crds --unified 6Diff output is per-resource — each changed resource gets its own header followed by a line-level diff. In a TTY, changes are color-coded: green for added, red for removed. In pipes/CI, +/- prefixes are used.
diff hr is strict: if a HelmRelease cannot be built on either side (chart download failure, unresolvable chart source), the diff fails with exit code 2 instead of producing a partial comparison — a HelmRelease silently missing from one side would otherwise show up as a false "added"/"removed" diff. Deterministic skips (suspended releases, unsupported Bucket sources) stay warnings since they affect both sides equally.
# Kubernetes resources are validated out of the box (schemas for
# --kubernetes-version, downloaded on first use and cached)
fluxview validate --path clusters/prod/flux/
# Add schemas for Flux CRDs and custom resources
fluxview validate --path clusters/prod/flux/ --schema-dir /schemas
# Pin a different Kubernetes schema version
fluxview validate --path clusters/prod/flux/ --kubernetes-version 1.34.0
# Strict mode: reject duplicated YAML keys; strict default-registry
# schemas also reject unknown fields
fluxview validate --path clusters/prod/flux/ --strict
# Full offline mode: unpack a kubernetes-json-schema checkout into the
# schema directory — native kinds validate locally, no network
mkdir -p schemas/kubernetes-json-schema
cp -r /path/to/kubernetes-json-schema/v1.36.1-standalone* schemas/kubernetes-json-schema/Validation uses the kubeconform engine. Schema sources, in priority order (first match wins):
--schema-dir(default:/schemas/or./schemas/):- JSON Schema files (
.json, kubeconform-compatible — e.g.crd-schemas.tar.gzfrom flux2 releases) - CRD YAML manifests (
.yaml/.yml, converted on the fly)
- JSON Schema files (
- A kubernetes-json-schema checkout found in or one level under
--schema-dir: directories namedv<version>-standalone[-strict]— the same layout the default registry serves. Grab the dirs for your--kubernetes-versionfrom yannh/kubernetes-json-schema,-standalone-stricttoo if you use--strict. - The default registry of Kubernetes schemas for
--kubernetes-version: before validation, the needed schemas are downloaded in parallel into the local cache (per-request timeout--schema-download-timeout, retries, interruptible) and validation then reads them from disk — it never waits on the network. A registry failure (other than a missing schema) fails the run (exit 2) instead of hanging or silently skipping.
Behavior:
- Resources without a matching schema are silently skipped; an unreadable
--schema-dir— or one containing a malformed CRD YAML file or a schema that cannot be converted — fails the run, so typos and corrupt schema sources don't silently disable CRD validation. --kubernetes-versionmust be a fullX.Y.Zversion (ormaster); anything else fails fast (exit 2) — a short form like1.36would 404 every native-kind schema and look like a green run while validating nothing. If the registry has no schema for any of the fetched kinds (a published-but-wrong version looks exactly like that), validate warns about the mass skip.- A failed kustomize build or a Kustomization whose
spec.pathis missing from the repository (suspended ones exempt) fails the run (exit 2) — a validation gate must not report success on a partial build. - Kustomizations whose
sourceRefnames an externalGitRepository(a repository other than the local origin, e.g. a dedicated CRDs upstream likekyverno/kyverno) are fetched into the git source cache and their resources are built, diffed and validated like local ones — including directories of loose YAML files without akustomization.yaml. The path always resolves against the upstream clone (Flux source-first semantics), even when a same-name directory exists locally. A broken manifest in the upstream fails the gate; an external source that cannot be fetched (unreachable upstream or--no-git-source-fetch, envFLUXVIEW_NO_GIT_SOURCE_FETCH— the kill switch for slow/offline networks) warn-and-skips in build/diff and leaves validate running: the unchecked Kustomizations are named in a warning, the local tree is still validated. Private upstreams authenticate from the machine environment, like native git: an SSH key (FLUXVIEW_GIT_SSH_KEY, ssh-agent or~/.ssh/id_*) with strict known_hosts verification (--git-source-ssh-known-hosts, TOFU via--git-source-ssh-accept-new), or https basic auth (FLUXVIEW_GIT_USERNAME/FLUXVIEW_GIT_PASSWORD,FLUXVIEW_GIT_TOKEN,~/.netrc) — https credentials apply only to hosts listed inFLUXVIEW_GIT_CREDENTIAL_HOSTS(fail-closed when unset; a manifest URL is untrusted input) — see the git source cache section. OCIRepository/Bucket sources stay outside the checkout and keep the missing-path behavior. --output json/--output junitemit a machine-readable report to stdout for CI.
# Everything the repository deploys, with versions
fluxview inventory --path clusters/prod/flux/
# Only Helm releases / only operator custom resources
fluxview inventory helm --path clusters/prod/flux/
fluxview inventory crs --path clusters/prod/flux/
# Filters and Markdown for MRs and wikis
fluxview inventory --path clusters/prod/flux/ -n monitoring --source helm,cr -o markdown
# Custom extraction rules
fluxview inventory --path clusters/prod/flux/ --rules ./inventory-rules.yamlHelm releases (1)
NAMESPACE NAME SOFTWARE VERSION CHART IMAGES
cert-manager cert-manager cert-manager v1.16.2 1.16.2 quay.io/jetstack/cert-manager-cainjector:v1.16.2, …
Operator custom resources (1)
NAMESPACE NAME KIND PARENT SOFTWARE VERSION IMAGES
victoria-metrics vmcluster VMCluster - VictoriaMetrics cluster v1.146.0-cluster none
Plain manifests (1)
NAMESPACE NAME SOFTWARE VERSION IMAGES
tools echo-server echo-server 0.9.2 ghcr.io/echo/echo-server:0.9.2
3 components (helm: 1, cr: 1, manifest: 1)
Components are collected from the same pipeline as build ks / build hr, entirely from the local repository. Every run shows an IMAGES column: manifest workloads carry their own images, CR images come from the rules, and HelmRelease templates render to resolve theirs (a warm chart cache keeps it cheap; none marks components without a known image):
- helm — one row per HelmRelease: chart name, resolved chart version (semver ranges show the selected version),
appVersion, chart source. Unavailable charts (Bucket source, chartRef) keep the spec version and warn. - manifest — Deployment/StatefulSet/DaemonSet/CronJob/Job workloads grouped by
app.kubernetes.io/name→part-of→ workload name; version from the main container's image tag (sidecars likeistio-proxyexcluded), falling back toapp.kubernetes.io/version, then the image digest. - cr — custom resources with user-provided extraction rules (JSONPath + optional regex over the matched value; the first non-empty field wins, none set → the operator default with a warning). No rules ship inside the binary — every cluster runs different operators, so the rules are yours:
.fluxview/inventory-rules.yamlin the repo root or--rules <file>.docs/inventory-rules-example.yamlcovers the reference fleet's operators with fields verified against it (VictoriaMetrics/VictoriaLogs, Strimzi Kafka, Banzai Vault, Grafana) — copy what you use.--all-crslists rule-less CRs with versionunknown. CRs rendered by a chart (from the always-on template render) appear ascrrows too, with the PARENT column carrying the HelmRelease's namespace/name; the same CR collected from manifests wins. - crd — CRD groups installed as separately versioned artifacts (renovate-pinned release URLs, upstream git tags) that can drift from the operator. Only groups with a known version show — from the
app.kubernetes.io/versionlabel or the pinned tag of the external GitRepository shipping them; groups with neither stay invisible. Chart-shipped CRDs are covered by their helm row.
Each section carries its own columns (CHART only in helm, KIND and PARENT in cr); --no-headers switches to flat rows with a fixed schema for scripts, and --split-umbrella splits an umbrella HelmRelease into one row per application (parent/app, version = the application's image tag; the split follows labels, not product boundaries).
--branch-orig <rev> adds a CHANGE column (+ added, - removed, ~ old → new updated, = unchanged) — an MR-ready version summary; exit code 1 when anything changed, 2 on any error. Output is byte-for-byte deterministic for equal input. Warnings and one render-progress line go to stderr, so -o markdown > inventory.md stays clean.
| Flag | Commands | Description |
|---|---|---|
-p, --path |
build, diff, validate, inventory | Path to cluster directory with Kustomization files |
-n, --namespace |
build, diff, validate, inventory | Filter output resources by namespace (default: all) |
--branch-orig |
diff, inventory | Branch/revision to compare against (default: auto-detect for diff) |
--color |
diff | Color mode: auto, always, never |
--unified |
diff | Context lines (default: 3) |
--skip-crds |
build, diff | Skip CustomResourceDefinition resources in output |
--strip-attrs |
build, diff | Comma-separated keys to strip (e.g. helm.sh/chart,status) |
--no-git-source-fetch |
build, diff, validate, inventory | Do not clone external GitRepository sources (no network at all): such Kustomizations warn-and-skip everywhere; validate names them in a warning and validates the rest — for slow or offline networks (default: false, env: FLUXVIEW_NO_GIT_SOURCE_FETCH) |
--schema-dir |
validate | Directory with schemas: kubeconform JSON files, CRD YAML manifests and/or a kubernetes-json-schema checkout (default: /schemas/ or ./schemas/) |
--kubernetes-version |
build, diff, inventory, validate | The Kubernetes version the run assumes, one knob for the whole pipeline. build/diff/inventory: the version rendered into chart capabilities — charts with an upper kubeVersion bound in Chart.yaml (e.g. < 1.37.0-0) check against it (k8s version syntax, 1.36 normalizes to 1.36.0, v prefix and prerelease suffixes accepted). validate: the default-registry schema set (full X.Y.Z like 1.36.1, or master — short forms are rejected there: they 404 every schema URL). Flag overrides env per command; the 1.36.1 default is deliberately below the k8s.io module versions (client-go v0.37 is what the Helm SDK derives its moving "latest" 1.37 from) — when raising it, re-check charts with kubeVersion constraints (#14) |
--schema-download-timeout |
validate | Per-request timeout for downloading Kubernetes schemas (e.g. 30s, 1m; 0 = no limit, Ctrl-C still interrupts; default: 30s) |
--strict |
validate | Reject duplicated YAML keys; strict default-registry schemas also reject unknown fields |
--skip-kind |
validate | Kinds to skip (repeatable or comma-separated): Deployment (any apiVersion) or apps/v1/Deployment |
--output |
validate | Output format: text (default, stderr), json or junit (stdout, per-resource statuses + summary) |
-o, --output |
inventory | Output format: table (default) or markdown (GFM, for MRs/wikis) |
--source |
inventory | Component sources: helm, manifest, cr, crd, comma-separated (default: all) |
--sort |
inventory | Sort keys: name, namespace, source, version (default: source,namespace,name) |
--rules |
inventory | Custom CR version-extraction rules file (default: .fluxview/inventory-rules.yaml in the repo root when present) |
--all-crs |
inventory | Also show custom resources without an extraction rule, with version unknown |
--split-umbrella |
inventory | Split an umbrella HelmRelease into one row per application (by app.kubernetes.io/name in the rendered chart); each row's version is the application's image tag. Note: the split follows labels, not product boundaries — a single product deployed as several deployments (cert-manager's controller/webhook/cainjector, kyverno's controllers) splits too |
--no-headers |
inventory | Flat data rows only (with the SOURCE column), no section titles, headers or summary — for scripts |
Cache flags (--helm-*, --remote-*, --kustomize-build-*, --git-source-*, --schema-*, --crd-schema-*) share one pattern: --<name>-cache-dir (disabled disables — all of them at once via FLUXVIEW_CACHE_HOME=disabled; empty, whitespace-padded and retired off/none values are rejected at parse time) and --<name>-cache-ttl where applicable (0 always bypasses). On slow networks, --helm-download-timeout and --remote-cache-timeout (0 = no limit) let downloads wait as long as the link needs instead of being cut off after 2m/30s, and --no-git-source-fetch (env FLUXVIEW_NO_GIT_SOURCE_FETCH) skips cloning external GitRepository sources altogether — see docs/caching.md.
Note on --kubernetes-version: FLUXVIEW_KUBE_VERSION (env) and the flag pin the Kubernetes version for the whole pipeline with priority flag > env > default — when a flag is set on a command, the env is not even read there.
The env grammar is strict and identical everywhere: a full X.Y.Z with an optional v prefix (1.35.7, v1.35.7). A short form (1.35), a bare v, master or garbage fails with exit 2, naming the variable — every command validates the pin the same way before doing anything else.
The flag grammar is per-command:
- the Helm commands (build/diff/inventory) accept k8s version syntax —
1.36=1.36.0,vprefix, prerelease suffixes, nomaster(charts render against concrete versions); - validate requires a full
X.Y.Zormaster(a short form would 404 every default-registry schema and silently check nothing).
What each command ends up with:
| Configured | build / diff / inventory (render) | validate (schemas) |
|---|---|---|
| nothing set | 1.36.1 |
1.36.1 |
FLUXVIEW_KUBE_VERSION=1.35.7 |
1.35.7 |
1.35.7 |
FLUXVIEW_KUBE_VERSION=1.35 or master |
error (exit 2) | error (exit 2) |
--kubernetes-version master |
error (exit 2) | moving master schema registry |
--kubernetes-version 1.35 (helm only) |
renders as 1.35.0 |
error (exit 2) |
| Code | Meaning |
|---|---|
| 0 | Success / no differences / all resources valid |
| 1 | Differences found (diff); version changes found (inventory with --branch-orig) |
| 2 | Error |
| 3 | Validation failed (validate only) |
Six independent on-disk caches — Helm charts, remote kustomize resources, kustomize build outputs, clones of external GitRepository sources, downloaded validation schemas, CRD schemas converted from YAML — all under ~/.cache/fluxview/ by default (relocatable wholesale via FLUXVIEW_CACHE_HOME; per-cache via FLUXVIEW_<NAME>_CACHE_DIR), so a single volume mount covers them. Both sides of a diff share one warm copy of everything. Defaults: indexes, floating remote refs and floating external source resolutions re-check every 10m, build outputs valid for 24h, validation schemas never expire (they are version-pinned); pinned external source clones (tag/commit) are immutable and never re-fetched.
Details, caveats, and per-cache flags/env vars: docs/caching.md.
docker run --rm -v $(pwd):/repo -w /repo ghcr.io/banschikovde/fluxview:latest \
build ks --path clusters/prod/flux/The image runs as a fixed non-root user; caches live inside the container unless mounted. For running as your host user, read-only repo mounts, and CRD schemas: docs/docker.md.
Kubernetes resource schemas are fetched automatically (kubeconform default registry, cached under ~/.cache/fluxview/schemas — see --kubernetes-version). CRD schemas come from --schema-dir (default /schemas/ or ./schemas/): for Flux CRDs, download the schemas:
wget -qO- "https://github.com/fluxcd/flux2/releases/download/v2.9.1/crd-schemas.tar.gz" | tar xzf - -C ./schemasFor other CRDs (VictoriaMetrics, Kyverno, etc.), place their YAML manifests alongside.
Example GitLab CI:
fluxview:diff:
image: ghcr.io/banschikovde/fluxview:latest
variables:
GIT_DEPTH: 0
before_script:
- git config --global --add safe.directory "${CI_PROJECT_DIR}"
- git fetch origin ${CI_DEFAULT_BRANCH}
script:
- fluxview diff ks --path clusters/prod/flux/ --branch-orig origin/${CI_DEFAULT_BRANCH}
--strip-attrs helm.sh/chart,checksum/cm,status --skip-crds --color never
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
fluxview:validate:
image: ghcr.io/banschikovde/fluxview:latest
before_script:
- git config --global --add safe.directory "${CI_PROJECT_DIR}"
script:
- fluxview validate --path clusters/prod/flux/ --schema-dir ./schemas --output junit > fluxview-validate.xml
artifacts:
when: always
reports:
junit: fluxview-validate.xmlThe validate job fails with exit 3 on invalid resources; artifacts.when: always still uploads the JUnit report, which GitLab renders in the merge-request test summary. Exit 2 means the run itself is broken (failed kustomize build, missing spec.path, unreadable schema dir) — no report is produced in that case.
To keep downloads between jobs, cache the cache directories — see docs/caching.md.
- Go, Cobra CLI
- go-git (Git SDK)
- kustomize SDK (build)
- Helm SDK (inflation)
- k8s.io/apiextensions-apiserver (CRD validation)
These are intentional non-goals (not planned unless requested). In build the affected HelmReleases are skipped with a warning rather than rendered incorrectly; in diff they are skipped on both sides (warning), which never fails the strict check.
- Bucket-sourced Helm charts are not supported —
HelmRelease.spec.chart.spec.sourceRef.kind: Bucketis not resolved (unlikeGitRepository, which works since the chart already lives in the local checkout). Bucket content lives in S3-compatible object storage and would require fetching it separately (endpoint/credentials fromspec.secretRef) — out of scope for now. HelmRelease.spec.chartRef.kind: HelmChartis not supported — onlychartRef.kind: OCIRepositoryis resolved. Referencing a standaloneHelmChartresource (used to share one chart artifact across multiple HelmReleases) is a rare, advanced pattern — HelmReleases using it are skipped with a warning ("has no chart name").
Apache-2.0