No description
  • Rust 74.5%
  • HTML 25%
  • CSS 0.3%
  • Dockerfile 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Bojan Rogalo 9b20f50c41
Some checks are pending
ci / check (push) Has started running
Use per-arch cargo cache ids in the Dockerfile
amd64 and arm64 build in parallel and shared one cargo registry cache,
which corrupted crate unpacking (File exists on .cargo-ok).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-21 17:53:17 +01:00
.cargo Serve the API at its own URLs 2026-11-20 18:07:52 +01:00
.forgejo/workflows Run the release workflow on the kvm runners 2026-11-21 17:34:58 +01:00
bin Move source and image to code.deseop.com 2026-11-21 17:26:38 +01:00
crates Add sharding (M4) 2026-11-21 14:30:02 +01:00
deploy Release 0.5.1 2026-11-21 17:30:35 +01:00
docs Move source and image to code.deseop.com 2026-11-21 17:26:38 +01:00
examples Add staged rollouts across clusters (M4) 2026-11-21 14:23:15 +01:00
testdata Release 0.5.0 2026-11-21 15:17:38 +01:00
website Release 0.5.1 2026-11-21 17:30:35 +01:00
xtask Move source and image to code.deseop.com 2026-11-21 17:26:38 +01:00
.dockerignore blox 0.1.0: standalone core (milestone M1) 2026-11-20 17:49:00 +01:00
.gitignore blox 0.1.0: standalone core (milestone M1) 2026-11-20 17:49:00 +01:00
Cargo.lock Release 0.5.1 2026-11-21 17:30:35 +01:00
Cargo.toml Release 0.5.1 2026-11-21 17:30:35 +01:00
CHANGELOG.md Run the release workflow on the kvm runners 2026-11-21 17:34:58 +01:00
Dockerfile Use per-arch cargo cache ids in the Dockerfile 2026-11-21 17:53:17 +01:00
README.md Run the release workflow on the kvm runners 2026-11-21 17:34:58 +01:00

blox

blox is a GitOps continuous-delivery system for Kubernetes, inspired by Flux CD and written in Rust with kube-rs. A single Blox resource describes the source (Git, OCI or Helm), how to render it (plain YAML, Kustomize or Helm) and which clusters to deploy to. One small bloxd binary runs as a standalone controller, a multi-cluster hub or an agent. The blox CLI can show you a diff before you push, explain why something isn't live, and move apps over from Flux one at a time, if and when you want to. It runs side by side with Flux on the same cluster.

Design: RFC-0001: blox architecture. Source: code.deseop.com/bloxcd/blox.

Status: 0.5.1 (milestone M4, hardening)

blox 0.5.1 is pre-alpha. See CHANGELOG.md for what it does and doesn't support yet.

Area Now Later
Sources Git over HTTPS (anonymous or username/password secret); branch, tag, commit, semver range, or remote HEAD. Helm charts from HTTPS repositories and OCI registries, by version or range. OCI artifacts in Flux's format SSH Git: not planned, use HTTPS with a read-only token
Render plain YAML, Kustomize (bundled binary, with patches), ${VAR} substitution, Helm (helm template, bundled binary; values and valuesFrom) Helm valuesFiles, post-renderers
Apply server-side apply in waves, prune with ownership checks, kstatus health, wait, dependsOn, impersonation, prune on delete, targetNamespace inventory spill to ConfigMap, drift events
CLI crds, preview, status, graph, reconcile, suspend, resume, diff, why, migrate --from-flux (Kustomizations and HelmReleases), cluster add/join/list diff against member clusters
Topology standalone; hub with BloxClusters reached by agent or kubeconfig (push), placement by labels, per-target overrides, staged rollouts across clusters; sharding over several bloxd Deployments

Build and test

cargo build --workspace
cargo test --workspace        # needs `git` on PATH for the source tests

CI runs on Forgejo Actions (.forgejo/workflows/): ci.yaml checks formatting, clippy, tests and cargo xtask check on every push and pull request. Pushing a tag such as v0.6.0 runs release.yaml, which builds the amd64 and arm64 image and pushes it to code.deseop.com/bloxcd/bloxd. That needs a runner labelled ubuntu-26.04-kvm where Docker runs, and the repository secrets REGISTRY_USER and REGISTRY_TOKEN.

Try it

# Render a directory locally, exactly as bloxd would:
cargo run -p blox -- preview testdata/plain --set ENV=prod

# Against a cluster (current kubeconfig context); needs kustomize and helm on PATH:
cargo run -p blox -- crds | kubectl apply -f -
cargo run -p bloxd                                   # in another terminal
kubectl create namespace apps
kubectl apply -f examples/podinfo.yaml
cargo run -p blox -- status -n apps podinfo

In-cluster

No image is published yet; it will live in the registry at code.deseop.com. Until then, build code.deseop.com/bloxcd/bloxd:0.5.1 yourself and make it available to your cluster, then install:

docker build -t code.deseop.com/bloxcd/bloxd:0.5.1 .  # Colima/k3s with the docker runtime sees this image directly
kubectl apply -k deploy                          # CRD, blox-system namespace, RBAC, bloxd Deployment
kubectl -n blox-system rollout status deploy/bloxd

To upgrade, build the new image and run kubectl apply -k deploy again: it updates the CRD and the Deployment, and existing Blox objects carry on.

Uninstall with kubectl delete -k deploy. Delete your Blox objects first if you want blox to prune what they applied.

Push webhooks

By default a Blox checks its source every interval. To reconcile as soon as you push, turn on bloxd's webhook receiver and point your forge at it:

kubectl -n blox-system create secret generic blox-webhook --from-literal=secret=$(openssl rand -hex 32)
kubectl -n blox-system rollout restart deploy/bloxd

Expose the bloxd-webhook Service at /hook through your ingress, then add a webhook in Forgejo, Gitea, GitHub or GitLab:

  • URL: https://<your ingress>/hook, content type JSON (GitHub's form encoding works too);
  • Secret: the value above (GitLab calls it the secret token);
  • Events: pushes, including tag pushes.

One receiver serves every repository. A push reconciles each Blox whose source.git.url is that repository (scheme, .git and case don't matter) and that follows the pushed ref: its branch, the default branch when no ref is set, or any tag for tag and semver refs. Unsigned deliveries are rejected with 401. Without the Secret the receiver stays off.

Signed artifacts

OCI sources can require a cosign signature, in the same form Flux uses. Keyless signatures from CI are the common case:

source:
  oci:
    url: oci://ghcr.io/stefanprodan/manifests/podinfo
    ref: { semver: "6.x" }
    verify:
      provider: cosign
      matchOIDCIdentity:
        - issuer: ^https://token\.actions\.githubusercontent\.com$
          subject: ^https://github\.com/stefanprodan/podinfo.*$

Or use your own keys: verify: { provider: cosign, secretRef: { name: cosign-keys } }, where every *.pub entry in the Secret is a trusted key.

An artifact without a matching signature is never applied. blox status shows who signed what is running (the SourceVerified condition). Keyless verification fetches Sigstore's trust root from tuf-repo-cdn.sigstore.dev, so bloxd needs outbound HTTPS to it.

Notifications

Admins define named sinks in bloxd's config, and each Blox picks the ones it wants. Credentials stay in a Secret in blox-system, so teams choose where their alerts go without seeing the URLs:

kubectl -n blox-system create secret generic blox-notify --from-literal=team-a=https://hooks.slack.com/services/...
kubectl -n blox-system create configmap bloxd-config --from-file=config.yaml=./bloxd-config.yaml
# bloxd-config.yaml
notify:
  sinks:
    - name: team-a-slack
      slack: { urlSecretRef: { name: blox-notify, key: team-a } }
      namespaces: [team-a]          # optional: which namespaces may use it
      events: [failed, recovered]   # optional: failed, recovered, applied (default all)
    - name: audit
      webhook: { urlSecretRef: { name: blox-notify, key: audit } }   # JSON POST

A Blox then sets notify: [team-a-slack].

  • Events: failed means Ready went False for a real failure; waiting on a dependency or an agent doesn't count. recovered means it came back after one. applied means a new revision was applied and is ready.
  • Multi-cluster: the hub sends one notification for every cluster the Blox is placed on.
  • Misconfiguration: an unknown sink name, or one not open to the Blox's namespace, shows up as a NotifyMisconfigured event on the Blox.
  • Config changes: bloxd picks up edits to the ConfigMap within a minute or so.

Multi-cluster

Run bloxd as a hub (BLOXD_MODE=hub in deploy/manager/deployment.yaml, or --mode=hub) and register each member cluster with a BloxCluster. A member connects in one of two ways:

  • Agent (recommended): the member runs bloxd with --mode=agent, which dials out to the hub's API server. The hub never holds credentials for the member, and the member needs no inbound access. Fetching and rendering happen on the member.
  • Push: the hub applies to the member directly with a kubeconfig stored in a Secret. That kubeconfig must authenticate with a token or a client certificate, because bloxd can't run exec plugins such as aws or gke-gcloud-auth-plugin.
kubectl get bloxclusters                        # CONNECTED shows whether the hub can reach it, or hears from its agent

blox cluster does the registration. Run add against the hub and join against the member, so neither side needs the other's kubeconfig:

# On the hub: register the cluster. This prints a join token.
blox cluster add eu-west-prod-1 -l env=prod -l region=eu-west --hub-url https://hub.example.com:6443
# On the member: install bloxd as that cluster's agent.
blox cluster join bloxjoin1.eyJ2Ijox...
# Back on the hub:
blox cluster list

--hub-url is the hub's API server as the member's pods see it. It defaults to the server in your kubeconfig. The token belongs to a blox-agent ServiceAccount in blox-cluster-<name> on the hub, which can only read what is assigned to that cluster, so treat it as a secret. join installs the CRDs and deploy/ with BLOXD_MODE=agent, and stores the hub kubeconfig in the blox-hub Secret. For push mode, run blox cluster add <name> --kubeconfig ./member.kubeconfig instead; nothing needs to be installed on the member.

A Blox then picks clusters by label, with overrides per target (substitute for plain and Kustomize, patches for Kustomize, values for Helm). See examples/podinfo-fleet.yaml:

targets:
  - local: true                     # the hub's own cluster, if you want it too
  - clusterSelector: { matchLabels: { env: prod } }
    patches: [ ... ]                # applied after render.kustomize.patches

status.clusters has a row per cluster, and Ready means ready on all of them.

  • Push clusters: the hub fetches once, then renders, applies and health-checks every one in parallel.
  • Agent clusters: each gets a copy of the Blox with its target's overrides. The agent reconciles that copy like any other Blox (kubectl get blox on the member shows it) and reports its status back.
  • Unplacing: with prune: true, a cluster that stops matching (say its labels change) has the Blox's objects removed. Deleting a BloxCluster leaves what blox applied there in place. An agent whose BloxCluster was deleted, or that can't reach the hub, keeps reconciling what it was last assigned.
  • Secrets and ServiceAccounts: Secrets that the Blox names (secretRef, valuesFrom) are read on the hub for push clusters, and on the member for agent clusters. serviceAccountName is used on each member, so that ServiceAccount must exist there.

Staged rollouts

By default a change reaches every cluster at once. With rollout, it moves through the clusters in waves instead:

wait: { timeout: 5m }               # required: a wave is done once its clusters are healthy
rollout:
  maxUnavailableClusters: 1         # clusters updating or failing at once (default 1)
  waves:
    - matchLabels: { env: staging }
    - matchLabels: { env: prod }    # clusters matching no wave, and local, go last
  • What is staged: anything that changes what a cluster runs, so both a new revision and a spec edit (values, patches, a new chart version). The hub fetches the source itself and pins every cluster to that exact revision (commit, digest or chart version), so a branch or semver range can't drift ahead on a member. With agents, the source's secretRef must therefore exist on the hub too.
  • Order: a wave starts once every cluster in the waves before it runs the change and is healthy. Within a wave, at most maxUnavailableClusters clusters are updating or failing at a time.
  • Failures halt it. A cluster that fails its health check stops the rollout where it is (Rollout of … halted (wave 1 of 2): staging-1: …). Clusters not yet reached stay on what they run. Push a fix or revert the change, and it goes through the waves again from the first.
  • Held clusters: an agent keeps reconciling its last assignment. A push cluster isn't re-applied until its wave comes, so drift there isn't corrected in the meantime.
  • Status: Ready is False with reason RollingOut while the rollout is under way, which doesn't trigger notifications; Blox objects that depend on it wait for the rollout to finish. status.rollout and blox status show the wave and how many clusters are updated, and each cluster's row says what it's held at.

Sharding

For a large fleet, spread the Blox objects over several bloxd Deployments. This works like Flux's sharding. Label a Blox with bloxcd.dev/shard: <name> and the instance started with --shard=<name> (BLOXD_SHARD) reconciles it. Unlabelled Blox objects stay with the main instance, the one started without --shard. Always run the main instance: in hub mode it is also the one that checks on the BloxClusters.

deploy/shard is a base for one shard. It's the main Deployment with its own name and Pod labels, so it needs the main install (deploy/) for the namespace, ServiceAccount and RBAC. Point an overlay at it for each shard:

# shard-a/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../blox/deploy/shard
nameSuffix: -a                                   # bloxd-shard-a
labels:
  - pairs: { app.kubernetes.io/instance: shard-a }
    includeSelectors: true
patches:
  - patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata: { name: bloxd-shard, namespace: blox-system }
      spec:
        template:
          spec:
            containers:
              - name: bloxd
                env:
                  - { name: BLOXD_SHARD, value: a }
                  - { name: BLOXD_MODE, value: hub }   # the same mode as the main instance
  • Moving a Blox between shards is a label change. The new owner picks it up right away, finalizer and inventory included.
  • Across shards: dependsOn works, because every instance caches every Blox and only reconciles its own. Push webhooks work too: point them at the main instance's Service, which triggers Blox objects in any shard.
  • Leader election is per shard, with the Lease bloxd-<name>, so each shard can run standby replicas.
  • A shard that isn't running leaves its Blox objects alone. blox status then says is bloxd --shard=<name> running?. Agents can't be sharded.

Layout

crates/blox-api      Blox, BloxCluster and BloxAssignment CRD types, CEL rules, condition helpers
crates/blox-source   git fetch (gitoxide) and helm pull into a shared artifact cache
crates/blox-render   plain YAML, kustomize and helm template; ${VAR} substitution
crates/blox-apply    server-side apply, inventory, prune, health
crates/blox-graph    dependsOn DAG: cycles, dependents, tree/dot output
bin/bloxd            the controller
bin/blox             the CLI
deploy/              CRDs (generated by `blox crds`), RBAC, Deployment
website/             bloxcd.dev: landing page plus generated API pages, schemas and CRDs
xtask/               `cargo xtask gen|check` for the generated files

Coming from Flux

blox runs next to Flux, so you can move one app at a time:

blox migrate --from-flux -n flux-system              # read-only: report to stderr, Blox YAML to stdout
blox migrate --from-flux -n flux-system podinfo > podinfo.blox.yaml   # one app, ready to commit
blox migrate --from-flux -n flux-system --apply podinfo               # hand it over now (bloxd must be running)

Kustomizations and HelmReleases both convert. --apply never recreates anything:

  1. It dry-runs the Blox against the live objects. If adopting them would change anything beyond blox's own labels, it shows the diff and stops before touching Flux. --allow-changes hands over anyway.
  2. It suspends the Flux object, creates the Blox, and waits for it to become Ready; server-side apply takes over the fields in place.
  3. It removes Flux's ownership labels from the objects.

After that, deleting the Kustomization or HelmRelease won't delete anything: Flux skips garbage collection and Helm uninstalls for suspended objects. If the Blox doesn't become Ready within --timeout (5m by default), it's removed with pruning off and Flux is resumed.

HelmReleases keep Flux's release name (<targetNamespace>-<name> unless set), so charts name their objects exactly as before. blox renders charts with helm template and keeps no Helm release history, as Argo CD does. Helm's release Secrets are left in place; don't helm uninstall a release after handing it over, because that would delete objects blox now manages.

Flux features blox can't express yet are reported as reasons the app can't be converted, never silently dropped. These include image overrides, components, SOPS decryption, substituteFrom, semverFilter, SSH Git URLs, Bucket sources, and Helm valuesFiles, post-renderers and valuesFrom with targetPath.

API reference and schemas

The API group is the project's domain, so every apiVersion is a URL:

URL What it is
bloxcd.dev/v1alpha1/blox Field reference for Blox. Each field has an anchor, e.g. #spec.source.git.url
bloxcd.dev/schemas/bloxcd.dev/blox_v1alpha1.json JSON Schema for editors and kubeconform (CRDs-catalog layout)
bloxcd.dev/crds/bloxes.bloxcd.dev.yaml The CRD, by name: kubectl apply -f <url>

To get validation and completion in your editor, start a Blox file with:

# yaml-language-server: $schema=https://bloxcd.dev/schemas/bloxcd.dev/blox_v1alpha1.json

These files, plus the CRDs in deploy/crds/, are generated from crates/blox-api. After changing the API types, run cargo xtask gen. cargo xtask check fails if anything is out of date.