Skip to content

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.

Get started What is chalkos

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.

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.

    Start

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

    Follow

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

    Operate

  • Run Kubernetes


    Plan a Kubernetes cluster on chalkos nodes and run its control plane on three nodes behind a virtual IP.

    Run

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

    Run

  • Build images


    Customise images and the installer with NixOS modules, then sign them for Secure Boot and publish them to a registry.

    Build

  • How chalkos works


    How a node is built, configured, booted, secured and upgraded, and how chalkos runs Kubernetes on those nodes.

    Learn

  • Reference


    Commands, config kinds, mkImages and image options, the node API, ports, the image layout and the glossary.

    Look up

  • Contribute


    The development setup, the tests, the layout of the code and how these pages are written.

    Contribute

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.