kzero-selfhosted

September 2, 2026 · View on GitHub

kzero-selfhosted — operator docs and examples for the kzero CLI

Operator-focused extras for kzero (latest release): how to run the CLI on a bastion or automation host, docker run notes, a sample YAML, and a kind smoke test. The application (Go CLI, tests, ghcr.io/hrodrig/kzero) lives in the kzero repo; this repo is documentation and examples only.

Tested with kzero v1.1.1 — kzero diff, native job/cronjob, Helm SDK v4; stable contract: default run.execution: native when omitted, process exit codes 0–4, run.api_watchdog / pipeline.stalled, notify.require_delivery, graceful SIGINT/SIGTERM, kzero doctor, kzero target --output slug, kzero analyze, verify/probe/preflight. deployment-models. CHANGELOG · kzero CHANGELOG.

Releases here: root VERSION and Git tags v<semver> on main name snapshots of this repository. Pushing a tag runs .github/workflows/release.yml to create the GitHub Release from CHANGELOG.md. Work in progress lands on develop first.

What is in this repo (and what is not)

In kzero-selfhosted	In hrodrig/kzero
Operator README, `run/docker`, `run/examples`	CLI source, `make release-check`, unit tests
kind e2e manifests + `make test-kind-e2e`	`ghcr.io/hrodrig/kzero` distroless images
`run/in-cluster/` Job + RBAC smoke manifests	In-cluster execution engine (InClusterConfig, Helm SDK)
Lab counter image build for e2e only	Binaries, `.deb` / `.rpm`, GoReleaser releases

Not shipped here: Docker Compose, a Helm chart that installs kzero as a long-running in-cluster controller, or bundled kubectl / helm in the runner image. Host/bastion runs remain the default; run/in-cluster/ documents Job-based runs with run.execution: native (see that README for RBAC and multi-namespace notes).

kzero is not self-contained (even with `run.execution: native`)

kzero orchestrates clusters from a host process. What you need on that host depends on config and run.execution:

Config / step kind	Typical host tools
`run.mode: dry-run`	kzero only; with `run.execution: native`, scale steps use server-side dry-run (API validation, no persisted replica change)
`kzero analyze`	kzero only
`deployment` / `statefulset` with `run.execution: native`	kzero + valid kubeconfig (client-go scale/wait; no `kubectl` for those steps)
Same workloads with `shell` or `auto` (fallback)	kzero + `kubectl` on `PATH` (or `command.kubectl`)
*`release.`** steps	`helm` + scripts under `helm.workspace`
`custom:`, phase hooks, per-step `pre` / `post`	`/bin/sh`; scripts often call `kubectl` themselves
kind e2e in this repo	kzero, `kubectl`, kind, Docker; live config uses `run.execution: native`; Postgres `pre:` hook still uses `kubectl exec`

The published GHCR image is distroless (only the kzero binary). It is fine for analyze / version. For live pipelines you either install kubectl / helm beside the container, use a custom image, or install kzero as a native package on the bastion (kzero — Install or update).

Contract and schema: kzero SPECIFICATIONS (including run.execution).

Where to start
Local e2e (kind)
Repository layout
Policies
License

Where to start

Goal	Start here
Install kzero (binaries, packages, GHCR)	kzero README — Install or update
Production `live` down / up / reset	run/standalone/README.md — bastion cron/systemd; kzero, kubeconfig, `kubectl` / `helm` as your YAML requires
`docker run` ( `analyze` / `version` )	run/docker/README.md — examples use `ghcr.io/hrodrig/kzero:v1.1.1`
Large platform reset (anonymized lab profile)	run/examples/platform-reset/
Full demo reset (`kzero-demo`, bootstrap scripts)	run/examples/full-reset-example/ · validation runbook
Copy-paste sample config	run/examples/kzero.sample.yml · reference hooks and infra-probe under run/examples/
CI / cron / YES-gated wrappers	run/docs/automation-and-pipelines.md
Smoke test on a disposable cluster	testing/kind/README.md — `make test-kind-e2e`

Local e2e (kind)

From the repository root, with Docker, kind, kubectl, and kzero v1.1.1+ on PATH (or KZERO_BIN):

make test-kind-e2e

Workloads-only (no kzero binary): make test-kind-workloads.

The full e2e script:

Creates a kind cluster and applies lab workloads in kzero-e2e (nginx web, Postgres-backed counter, Redis, RabbitMQ, Postgres, nginx StatefulSet + PVC, lightweight obs Deployment).
Phase 1 — drives the counter HTML UI (0 → increment ×3 → 3).
Phase 2 — kzero analyze, then kzero down (dry-run plan, then live) and kzero up using run.execution: native in testing/kind/kzero-e2e.yaml; Postgres pre-down hook truncates e2e_scratch via kubectl exec.
Phase 3 — UI count back to 0.
Phase 4 — deletes the cluster on exit.

Details, env vars, and manifest list: testing/kind/README.md · overview: testing/README.md.

Repository layout

Path	Purpose
`run/`	Operator overview — run/README.md
`run/standalone/`	Bastion cron / systemd — run/standalone/README.md
`run/docs/`	CI/cron automation — run/docs/automation-and-pipelines.md
`run/docker/`	`docker run` examples (run/docker/README.md)
`run/examples/`	Sample YAML, hooks, infra-probe (run/examples/README.md)
`testing/kind/`	kind cluster manifests, e2e configs, lab counter Dockerfile
`testing/scripts/`	`kzero-kind-e2e.sh` driver
`assets/`	README hero image
`Makefile`	`make help`, `make release-check`, `make test-kind-e2e`, `make test-kind-workloads`
`CHANGELOG.md`	kzero-selfhosted release history

Application tests and make release-check: clone hrodrig/kzero.

Policies

CONTRIBUTING.md — scope, PR expectations, and release flow.
SECURITY.md — reporting vulnerabilities.
CODE_OF_CONDUCT.md — community standards.

License

See LICENSE (MIT).