From fa60ef24088ccb2d6242052b39512d038b7dee43 Mon Sep 17 00:00:00 2001 From: Jonathan Lebon Date: Wed, 27 May 2026 16:29:37 -0400 Subject: [PATCH] tree: add a more complete README Even though we're not fully functional yet, let's at least have something basic so people understand this repo. Closes #37. Assisted-by: Pi (Claude Opus 4.6) --- README.md | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 195 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b7194c9..9c23259 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,198 @@ # Bootc Operator +A Kubernetes operator for managing [bootc] nodes. + > [!WARNING] -> Under construction. Come back later. +> This project is in early development and not yet fully functional. APIs may +> change. + +## Table of Contents + +- [Motivation](#motivation) +- [Highlights](#highlights) +- [Installation](#installation) +- [How It Works](#how-it-works) +- [Usage](#usage) + - [Creating a pool](#creating-a-pool) + - [Monitoring a rollout](#monitoring-a-rollout) + - [Pausing and resuming](#pausing-and-resuming) + - [Rolling back](#rolling-back) +- [Related Projects](#related-projects) + +## Motivation + +[bootc] lets you build and deploy image-based Linux systems using container +tools. It a strong candidate for managing Kubernetes cluster nodes. At the same +time, it also provides a common distro-agnostic API through which to manage +these nodes. + +The Bootc Operator then exposes this bootc API to the Kubernetes control plane +in pure operator declarative fashion: you define the desired state your hosts +should be in, and the operator handles the reconciliation. This includes image +updates, but also future bootc enhancements like dynamic config overlays, +sysexts, etc. See the [PRD](docs/PRD.md) for more details. + +## Highlights + +- **Distro-agnostic** — Works with any bootc-based OS image, not tied to any + Kubernetes distribution. +- **Declarative** — Specify your node requirements in a declarative way through + CRDs. +- **bootc-native** — Tight integration with current and future bootc features + like soft-reboot, non-disruptive staging, dynamic config overlays, live + apply, etc. + +## Installation + +Deploy from the kustomize config: + +```shell +kubectl apply -k https://github.com/jlebon/bootc-operator//config/default +``` + +This creates the `bootc-operator` namespace and deploys the controller and +daemon. The operator does nothing until you create a BootcNodePool. + +> [!NOTE] +> The operator namespace requires a [Pod Security Admission] exemption for the +> `privileged` level. The daemon DaemonSet runs privileged to execute bootc +> commands on the host. + +## How It Works + +The operator consists of two components: + +- A **controller** (Deployment) that watches BootcNodePool resources, resolves + image digests, manages pool membership, and drives the rollout state machine + (cordon, drain, reboot slot management). +- A **daemon** (DaemonSet) that runs on each managed node. It watches its own + BootcNode resource, executes bootc commands on the host, and reports status + back. + +The controller and daemon communicate exclusively through BootcNode resources: +the controller writes `spec` (what the node should do), the daemon writes +`status` (what the node is doing). There is no direct communication between +them. + +``` + BootcNodePool (user-created) + │ + ▼ + ┌─────────────────┐ + │ Controller │ + │ (Deployment) │ + └────────┬────────┘ + │ creates/updates + ▼ + BootcNode.spec ──────► BootcNode.status + (desired state) (observed state) + │ ▲ + ▼ │ + ┌─────────────────┐ │ + │ Daemon ├───────────┘ + │ (DaemonSet) │ reports + │ per node │ + └─────────────────┘ +``` + +## Usage + +### Creating a pool + +A BootcNodePool defines a group of nodes and the OS image they should run. +Nodes are selected by label: + +```yaml +apiVersion: node.bootc.dev/v1alpha1 +kind: BootcNodePool +metadata: + name: workers +spec: + nodeSelector: + matchLabels: + node-role.kubernetes.io/worker: "" + image: + ref: quay.io/example/myos@sha256:abc123... +``` + +The operator creates a BootcNode for each matching node, labels it with +`bootc.dev/managed`, and begins staging the image. To update the OS, change +`spec.image.ref` to a new digest. Tags will also be supported. + +### Monitoring a rollout + +Pool status shows rollout progress: + +```shell +kubectl get bootcnodepool workers -o yaml +``` + +```yaml +status: + targetDigest: sha256:abc123... + nodeCount: 10 + updatedCount: 7 + updatingCount: 2 + degradedCount: 1 + conditions: + - type: UpToDate + status: "False" + reason: RolloutInProgress + message: "7/10 updated; 2 staging, 1 rebooting" +``` + +Individual node status is available via BootcNode resources: + +```shell +kubectl get bootcnodes +``` + +### Pausing and resuming + +To pause a rollout (in-progress staging completes, but no new reboots start): + +```shell +kubectl patch bootcnodepool workers --type merge -p '{"spec":{"rollout":{"paused":true}}}' +``` + +To resume: + +```shell +kubectl patch bootcnodepool workers --type merge -p '{"spec":{"rollout":{"paused":false}}}' +``` + +### Rolling back + +To roll back, change `spec.image.ref` to the previous digest. Nodes already +running that image are left alone. Nodes that were updated go through the +normal staging and reboot cycle to return to the previous image. + +## Related Projects + +### Machine Config Operator (MCO) + +The [MCO] manages bootc hosts (such as RHEL CoreOS) on [OpenShift]. It is +powerful but tied to OpenShift. A primary goal of the Bootc Operator is to +support being leveraged by existing distributions where it may be driven by a +higher-level operator such as the MCO. + +### Flightctl + +[Flightctl] is a fleet management service for edge devices, primarily targeting +bootc hosts. It shares similar functionality around rollouts but operates +outside the Kubernetes operator pattern. + +### Kured + +[Kured] handles reboot coordination for Kubernetes nodes and works well with +bootc. The Bootc Operator covers similar ground but tightens the scope to bootc +hosts, taking advantage of image-based features like update staging and OS +rollbacks as part of the rollout strategy, and overall exposing bootc APIs +directly. + +[bootc]: https://github.com/bootc-dev/bootc +[Flightctl]: https://flightctl.io/ +[Kured]: https://kured.dev/ +[MCO]: https://github.com/openshift/machine-config-operator +[OpenShift]: https://www.redhat.com/en/technologies/cloud-computing/openshift +[Pod Security Admission]: https://kubernetes.io/docs/concepts/security/pod-security-admission/