Skip to content
banschikovdePublic

About

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.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

fluxview

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.

Quick start

go install github.com/banschikovde/fluxview/cmd/fluxview@latest

or via Docker:

docker run --rm -v $(pwd):/repo -w /repo ghcr.io/banschikovde/fluxview:latest \
  diff ks --path clusters/prod/flux/ --branch-orig master

Features

  • 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; table or GFM markdown output, MR-ready change summary via --branch-orig
  • Recursive Kustomization discovery following spec.path into 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)

Commands

Resource types accept the full name as well as the short alias: kustomization = ks, helmrelease = hr.

build — assemble resources

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 — compare changes

# 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 6

Diff 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.

validate — validate resources

# 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):

  1. --schema-dir (default: /schemas/ or ./schemas/):
    • JSON Schema files (.json, kubeconform-compatible — e.g. crd-schemas.tar.gz from flux2 releases)
    • CRD YAML manifests (.yaml/.yml, converted on the fly)
  2. A kubernetes-json-schema checkout found in or one level under --schema-dir: directories named v<version>-standalone[-strict] — the same layout the default registry serves. Grab the dirs for your --kubernetes-version from yannh/kubernetes-json-schema, -standalone-strict too if you use --strict.
  3. 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-version must be a full X.Y.Z version (or master); anything else fails fast (exit 2) — a short form like 1.36 would 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.path is 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 sourceRef names an external GitRepository (a repository other than the local origin, e.g. a dedicated CRDs upstream like kyverno/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 a kustomization.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, env FLUXVIEW_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 in FLUXVIEW_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 junit emit a machine-readable report to stdout for CI.

inventory — software inventory of the cluster

# 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.yaml
Helm 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 like istio-proxy excluded), falling back to app.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.yaml in the repo root or --rules <file>. docs/inventory-rules-example.yaml covers the reference fleet's operators with fields verified against it (VictoriaMetrics/VictoriaLogs, Strimzi Kafka, Banzai Vault, Grafana) — copy what you use. --all-crs lists rule-less CRs with version unknown. CRs rendered by a chart (from the always-on template render) appear as cr rows 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/version label 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.

Flags

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, v prefix, prerelease suffixes, no master (charts render against concrete versions);
  • validate requires a full X.Y.Z or master (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)

Exit codes

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)

Caching

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

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.

CRD schemas

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 ./schemas

For other CRDs (VictoriaMetrics, Kyverno, etc.), place their YAML manifests alongside.

CI

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.xml

The 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.

Technology

  • Go, Cobra CLI
  • go-git (Git SDK)
  • kustomize SDK (build)
  • Helm SDK (inflation)
  • k8s.io/apiextensions-apiserver (CRD validation)

Limitations

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: Bucket is not resolved (unlike GitRepository, 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 from spec.secretRef) — out of scope for now.
  • HelmRelease.spec.chartRef.kind: HelmChart is not supported — only chartRef.kind: OCIRepository is resolved. Referencing a standalone HelmChart resource (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").

License

Apache-2.0

About

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.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages