chalkos¶
chalkos builds API-driven, immutable Linux distributions from NixOS modules. It ships layers for Kubernetes nodes and routers, and its images carry the schemas of the config they accept.
A machine that is changed in place drifts. Packages, hand edits and half-done upgrades pile up until nobody can say what a node runs. Talos Linux answers this for Kubernetes with a read-only image, no logins and an API that manages each node. chalkos takes that operating model and makes the distribution itself something an image author builds. An image is a set of NixOS modules: a layer that chalkos ships, such as Kubernetes or the router, the services and drivers the nodes need, and config kinds of the image's own. Each node boots the exact image that was built and signed, and changes only through its API.
Choose your path¶
Start with the path that matches your work. Each one assumes the one before it, so an image author knows the quick start and a contributor knows both. Each release publishes generic images for clusters that need no image of their own, as Releases describes; every other image is built with Nix.
-
Use chalkos
For operators. Run a lab cluster of two virtual machines on one machine in about 15 minutes, or a lab router. Then take the cluster to real machines with Build a cluster on real machines, or do one task at a time from Operate nodes.
-
Customise images
For image authors. Write your first image flake, then your first extension in about 15 minutes on the lab. The rest of Build images covers one task per page.
-
Contribute
For contributors to chalkos itself. Enter the development shell, run one package's tests and commit a first change in about 10 minutes.
A Nix flake calls mkImages, which builds each image the flake names, for its platform, from NixOS
modules. An image holds a read-only Nix store on dm-verity, a unified kernel image (UKI) that
Secure Boot verifies, and the JSON Schemas of its config kinds. YAML documents in the style of
Kubernetes objects configure each node. chalkctl checks them against the node's image, then
delivers the documents and the images to the nodes, and never runs Nix. chalkd, the agent on each
node, applies the config and writes an upgrade into the inactive one of two A/B slots. When the new
image does not boot healthy, the node returns to the image before.
What chalkos is¶
- A distribution builder
- An image is built from ordinary NixOS modules and the packages of nixpkgs, so it can add any software, driver or kernel setting. The Kubernetes layer makes a node much like a Talos node; the router layer makes it a router in the manner of VyOS, managed the same way.
- Config the image checks
- A module declares a config kind as Kubernetes declares a custom resource: fields, defaults and CEL rules. The image carries the kinds' schemas, so chalkctl refuses a mistake against the image a node runs before the node sees it.
- Config per image
- A node keeps a config slot for each image it holds. An upgrade brings config that the new image checks itself, while the image before keeps its own, so a kind can change between images and a rollback still boots with config it understands. Change a kind incompatibly shows such a change.
- Verified from build to boot
- Secure Boot verifies the signed UKI, and the UKI pins the root hash of the store. dm-verity then checks every block the node reads against what Nix built. The TPM unseals the node's encrypted state only under the same Secure Boot state.
- Appliance nodes
- Nodes have no SSH and no login. chalkd serves an API over mutual TLS, and the role in a client's certificate decides what it may call. A node boots a new image with a fixed number of tries and returns to the image before when none of them comes up healthy.
- A toolkit to extend and test
- An extension renders a service's config files from its kinds, reloads the service on a change and
adds diagnostics. Its tests run in
nix flake check, and chalklab runs a whole cluster as virtual machines on one host.
Explore the docs¶
-
Get started
What chalkos is, and a lab cluster of two virtual machines on one machine. Then what real machines need.
-
Guides
Whole projects from start to end: a cluster on three real machines, a BGP extension written from scratch, and an IPv6 home lab with a router.
-
Operate nodes
Install, upgrade, recover and troubleshoot nodes with chalkctl and YAML files. The machine that runs chalkctl needs no Nix. Take the generic images of a release, or build images from a template or an example with
nix buildfirst. -
Run Kubernetes
Plan a Kubernetes cluster on chalkos nodes and run its control plane on three nodes behind a virtual IP.
-
Run a router
Forward between a node's networks, filter and translate what passes with zones, policies and NAT rules, and exchange routes over BGP.
-
Build images
Customise images and the installer with NixOS modules, then sign them for Secure Boot and publish them to a registry.
-
How chalkos works
How a node is built, configured, booted, secured and upgraded, and how chalkos runs Kubernetes on those nodes.
-
Reference
Commands, config kinds,
mkImagesand image options, the node API, ports, the image layout and the glossary. -
Contribute
The development setup, the tests, the layout of the code and how these pages are written.
Status
chalkos is before 1.0. Until then, the config kinds, all at v1alpha1, the mkImages
arguments, the image options, the commands and the node API change between releases without
migrations. A cluster may need its YAML or flake edited, or its nodes reinstalled, when it
moves to a newer chalkos. Run it in labs and test clusters.