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.4.5. No build-from-source, no simulators.

Get started

Bring up a management cluster and install banlieue.

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

Providers

One guide per backend, in the order we recommend them: Cloud Hypervisor first.

  • Cloud Hypervisor Provider

    The reference backend. A bare-metal Linux host (Debian, Kairos, any systemd distribution) to VMs banlieue schedules: the VMM and firmware from GitHub or your mirror, a guest per systemd unit under its own uid, a budgeted guests' slice the scheduler places against, OCI images by digest, a vTPM per guest, and measuring what the VMs cost the host.

  • Cloud Hypervisor: Host Internals

    Every unit setting, slice, polkit rule, tmpfiles entry and guest identity the Cloud Hypervisor host needs, why each is there, and what breaks without it.

  • 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 run VMs on it: image import, the LibvirtMachine lifecycle, cloud-init and vTPM, through a first-party RPC client, with 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.

  • Proxmox VE Provider

    Register a Proxmox node with a least-privilege API token and run VMs as full clones of a template, with cloud-init delivered as a NoCloud ISO.

Workloads

Warm pools, single-use claims, the identity layer above them, and Cluster API.

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

  • VirtualMachine Claims

    Take one warm member out of a pool, for one identity, once — binding, ttlSeconds, why release is always deletion, and why subject must never carry a credential.

  • Isolated Sandbox Segment

    Put sandboxes on a segment with no router and let them out only through gateway VMs: the network classes, the two-NIC gateway, a pool with no default route, and how to check it is isolated.

  • Sandbox Identity with mediatore

    What happens after the bind: the companion broker that turns a claim into an attested, delegated identity — and why the SPIRE server belongs on its own cluster in an enterprise. An entry point; the deep docs live in the mediatore repo.

  • The Claim Flow, End to End

    The same story as sequence diagrams: kubelogin and the OIDC flow that establishes who you are, the admission checks, the bind race, the state machine, and the two finalizers that make release mean something.

  • Cluster API

    Install banlieue as a clusterctl infrastructure provider with clusterctl init --infrastructure banlieue, and the scoped ClusterRole that authorises Cluster API's manager on the infrastructure kinds only.

Images

Building the disk images VMs boot from.

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

Operations

Running banlieue day to day.

  • Observability

    Prometheus metrics on every role, scraping operator-spawned provider pods, the Grafana dashboard, opt-in OpenTelemetry traces, and why a standby replica reports Ready.

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.4.5. 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.4.5 --depth 1 https://github.com/firestoned/banlieue
cd banlieue