Skip to content

Guides

Production-oriented, step-by-step guides for installing and operating banlieue on a real cluster, using the released container image ghcr.io/firestoned/banlieue:v0.1.0. No build-from-source, no simulators.

  • Host Bootstrap

    Bare metal to a running k0s cluster: provision a KVM hypervisor, or prepare a workstation and discover a vSphere estate — the step before every other guide here.

  • End-to-End Setup

    The whole chain in one diagram: bootstrapping the management cluster, installing banlieue, registering a backend, building an image, and provisioning a VM — with links out to every guide below.

  • Core Controller

    Install the CRDs, the banlieue-controller, RBAC, and the optional ValidatingAdmissionPolicies — the foundation every provider builds on.

  • vSphere Provider

    From an empty cluster to a scheduled VirtualMachine on vCenter: the provider Deployment, credentials, Provider, VMClass, VMImage, and a VirtualMachine — every file and kubectl apply.

  • libvirt Provider

    Register a libvirt/KVM host over mutual TLS and import a guest image onto it — a first-party RPC client, no libvirt-dev and no virsh.

  • cloud-init on libvirt

    How spec.userData reaches a guest as a NoCloud seed, why the image is Joliet, and how to tell from outside whether cloud-init consumed it.

  • VirtualMachine Pools

    Keep already-provisioned VMs standing by so a consumer does not wait out provisioning — sizing, image rollout, and the one field that fails silently if you guess it.

  • Setting up the Kairos Operator

    Install the third-party Kairos operator banlieue's image-build pipeline depends on, and confirm it with a smoke-test build.

  • Using banlieue-imagebuilder

    Turn an OCI/Kairos image into a VMImage raw disk automatically (ADR-0010) — install banlieue-imagebuilder, watch the build, and see exactly what's implemented today versus tracked as a follow-up.

Looking to hack on banlieue itself?

Building from source, running against kind/vcsim, and the *-run-local workflow live under Developer → Local Development.

Conventions used in these guides

  • Everything is pinned to the released tag v0.1.0. Manifests live in the repository under deploy/ at that tag; the guides apply them directly.
  • All workloads run in the banlieue-system namespace under the Pod Security restricted profile.
  • A cluster of Kubernetes 1.30+ is assumed (required for the ValidatingAdmissionPolicies; the controllers themselves work on older clusters).
# Pin the repo to the release so the manifests match the image.
git clone --branch v0.1.0 --depth 1 https://github.com/firestoned/banlieue
cd banlieue