GitOps for Kubernetes · inspired by Flux CD

From Git to cluster in one resource.

blox builds on the ideas Flux CD made standard and folds source, rendering and deployment into a single Blox object. One small Rust controller fetches it, renders it, applies it, and tells you in plain words when something is wrong.

Flux CD

2 objects · 2 statuses
GitRepository
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata: { name: podinfo, namespace: apps }
spec:
  interval: 5m
  url: https://github.com/stefanprodan/podinfo
  ref: { tag: "6.7.0" }
Kustomization
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: { name: podinfo, namespace: apps }
spec:
  interval: 5m
  sourceRef: { kind: GitRepository, name: podinfo }
  path: ./kustomize
  prune: true
  wait: true

Composable building blocks. One source can feed many Kustomizations, and each object has a focused job.

blox

1 object · 1 status
Blox
apiVersion: bloxcd.dev/v1alpha1
kind: Blox
metadata: { name: podinfo, namespace: apps }
spec:
  interval: 5m
  source:
    git:
      url: https://github.com/stefanprodan/podinfo
      ref: { tag: "6.7.0" }
      path: ./kustomize
  render: { kustomize: {} }
  targets: [ { local: true } ]
  prune: true
  wait: {}
  • source · fetch
  • render
  • targets · apply
  • prune
  • wait

Everything in one place. One Ready condition to read. Blox objects on the same repository still share a single fetch, from a cache inside the controller.

Visibility

It tells you what's wrong, and where.

Every status message says what happened, to which object, and what blox will do next. The output below is adapted from the M1 end-to-end run on a k3s cluster.

blox status
$ blox status -n apps
NAME             READY  REVISION            MESSAGE
apps/web         True   main@sha1:bfe7b75   Applied main@sha1:bfe7b75a53b9 (3 objects: 3 unchanged); all healthy
apps/fresh       True   main@sha1:23b7e68   Applied main@sha1:23b7e68d293e (1 object: 1 created)
apps/migrations  False  -                   Job/apps/migrate is unhealthy: job failed: Job has reached the specified backoff limit
apps/podinfo     True   6.7.0@sha1:0b1481a  Applied 6.7.0@sha1:0b1481aa8ed0 (3 objects: 3 unchanged); all healthy
blox graph
$ blox graph -n apps
apps/web
└── platform/base

$ blox status -n platform base
platform/base  False
  dependency cycle:
  platform/base -> apps/web
  -> platform/base

$ 

Waits on dependencies.dependsOn holds a Blox until its dependencies are Ready, then starts it within seconds.

Names the cycle.A circular dependsOn is reported with its full path and marked Stalled, instead of retrying forever.

Shows the failing object.Health failures point at the object and quote its own reason, such as a Job's backoff limit or a stuck rollout.

How it works

One reconcile, six steps.

bloxd runs these in order for every Blox, on its interval, or immediately when you run blox reconcile.

  1. 01

    Fetch

    Shallow-fetches one revision with gitoxide. Blox objects on the same repo and ref share one fetch.

  2. 02

    Render

    Reads plain YAML, or runs Kustomize with your patches. ${VAR} values can differ per target.

  3. 03

    Apply

    Server-side apply as field manager blox. CRDs and Namespaces go first, then the rest in waves.

  4. 04

    Prune

    Deletes what left Git, but only objects still labelled as belonging to this Blox.

  5. 05

    Wait

    Checks health the kstatus way: rollouts, Jobs, PVCs, and the Ready condition of custom resources.

  6. 06

    Report

    Writes one Ready condition with an actionable message, and a Kubernetes Event when something changed.

Design goals

Where blox takes a different path.

In M1

One resource per app

Source, renderer, targets, health and dependencies live in one Blox. The API server rejects contradictory specs, such as two sources, with CEL rules.

In M1

Status you can act on

blox status, blox graph and blox preview work today. blox diff shows what a push will change before you push it, and blox why explains any object.

In M1

One small binary

Where Flux runs a set of focused controllers, blox runs everything in one bloxd process with shared caches and one set of watches. The target is under 50 MB of memory when idle.

In M3

Multi-cluster built in

The same binary runs as a hub or an agent. Agents connect out to the hub, so the hub never stores credentials for member clusters. A Blox picks clusters by label, with overrides per cluster, and blox cluster join sets up an agent.

With Flux

Good neighbours with Flux.

Pull-based reconciliation, server-side apply, pruning, health gating and tenant impersonation are ideas blox learned from Flux. The two run side by side on one cluster, and blox keeps Flux's formats where it can, so you can try it on one app without touching the rest.

  • Runs next to an existing Flux install, tested on k3sIn M1
  • Flux-style ${VAR} and ${VAR:=default} substitutionIn M1
  • Inventory ids in Flux's namespace_name_group_Kind formatIn M1
  • Per-Blox ServiceAccount impersonationIn M1
  • Flux OCI artifacts readable as-is, from the same registriesIn 0.3
  • blox migrate --from-flux hands one Kustomization or HelmRelease over, with nothing recreatedIn 0.2
  • Helm charts from the same HTTPS and OCI repositories, with Flux's release namesIn 0.2
  • targetNamespace, with the same meaning as in FluxIn 0.2

History

Git to cluster, so far.

blox stands on ten years of work by the Flux, Argo and OpenGitOps communities. Here's how pulling from Git became the normal way to run Kubernetes.

  1. 2015

    Kubernetes 1.0

    Deploying mostly means kubectl apply, run by a person or pushed from a CI pipeline that holds cluster credentials.

  2. 2016

    Weaveworks open-sources Flux

    An agent inside the cluster watches a Git repository and applies what it finds. The cluster pulls instead of being pushed to.

  3. 2017

    The practice gets a name

    Alexis Richardson's post "Operations by Pull Request" on the Weaveworks blog calls it GitOps.

  4. 2018

    Argo CD

    Intuit open-sources Argo CD, a pull-based delivery tool with a web UI. GitOps now has more than one home.

  5. 2019

    Flux joins the CNCF

    Weaveworks donates Flux to the Cloud Native Computing Foundation as a sandbox project.

  6. 2020

    The GitOps Toolkit

    Flux is rebuilt as a set of composable controllers, which becomes Flux v2. The CNCF GitOps Working Group forms in November.

  7. 2021

    OpenGitOps 1.0

    The working group publishes four principles: declarative, versioned and immutable, pulled automatically, continuously reconciled. Flux moves to CNCF incubation.

  8. 2022

    Flux graduates

    Flux becomes a CNCF graduated project on 30 November, and Argo graduates soon after.

  9. 2023

    Flux 2.0

    General availability in July, with stable v1 APIs and horizontal scaling and sharding for its controllers.

  10. 2024

    Flux carries on

    Weaveworks closes in February. Flux keeps going as a CNCF project, with its maintainers backed by other companies.

  11. 2026

    Flux turns ten

    The project marks ten years in July. Happy birthday, Flux.

  12. 2026

    blox 0.3

    A new take on the same idea, built on everything above: one resource per app and one small controller, written in Rust. It reads Git, Helm charts and Flux OCI artifacts, and offers a way over from Flux that recreates nothing. What comes next.

Roadmap

Where blox is today.

M1 · v0.1.0

Standalone core

  • Git source, plain YAML and Kustomize
  • Apply, prune, health, dependsOn
  • status, graph, preview
  • Tested end to end on k3s 1.35

M2 · v0.2.0 and v0.3.0

Parity and migration

  • Helm sources and rendering
  • diff, why and migrate --from-flux
  • Semver refs and push webhooks
  • OCI artifact sources

M3 · v0.4.0

Multi-cluster

  • BloxCluster registration
  • Hub and agent modes
  • Label-based placement
  • Per-cluster overrides

M4 · v0.5.0

Hardening

  • Slack and webhook notifications
  • cosign verification
  • Staged rollouts across clusters
  • Leader election and sharding

Quickstart

Run it against your cluster.

blox has no published binaries yet. With Rust, kubectl and kustomize on your PATH, this clones the source, installs the CRD, starts the controller against your current kubeconfig context, and deploys podinfo.

To try the renderer without a cluster, run cargo run -p blox -- preview testdata/plain --set ENV=prod.

git clone https://code.deseop.com/bloxcd/blox && cd blox
cargo run -p blox -- crds | kubectl apply -f -
cargo run -p bloxd            # leave running

kubectl create namespace apps
kubectl apply -f examples/podinfo.yaml
cargo run -p blox -- status -n apps podinfo