Skip to content

How chalkos works

These pages are for operators, image authors and contributors who want the mechanism behind a task. They explain how a node is built, configured, booted, secured and upgraded, and where each protection stops. For the whole model on one page first, read What is chalkos.

The node OS

These pages describe the operating system of a node: the base that every image carries. A layer, a predefined set of NixOS modules that chalkos ships and an image lists in its modules, adds one role on top of the base, and an image carries one layer at most. The Kubernetes layer and the router layer below describe what chalkos adds to run Kubernetes on it, or to route between networks.

  • How a node works


    The machines that build, drive and run a node, and the stages of a node's life.

    Read

  • Architecture


    The parts of chalkos, where each one runs, and how chalkd picks its mode.

    Read

  • The image


    What an image holds: the erofs store on dm-verity, the signed UKI and the A/B slots.

    Read

  • Boot, health and rollback


    How a node boots, decides whether a boot is healthy, and falls back from an image that is not.

    Read

  • Config and the inventory


    How YAML config documents describe each node, how the inventory gives them out, and how a node applies them.

    Read

  • The config pipeline


    How a delivery passes a node's documents through rules, outputs and effects, and what happens at boot and after an upgrade.

    Read

  • Storage and encryption


    STATE, VAR and volumes, how they are encrypted and unlocked, and how they change after install.

    Read

  • Networking


    How a node configures its interfaces with networkd, filters traffic with nftables and keeps its clock.

    Read

  • Security model


    What Secure Boot, the TPM, the OS CA and client roles protect, and what they do not.

    Read

  • Certificates


    The OS CA, the node CA and the node API's certificates, how they are renewed and rotated, and why the clock matters.

    Read

  • Upgrades


    How a new image reaches a node, how the node writes and checks it, and how it boots it on trial.

    Read

Kubernetes layer

These pages describe what chalkos adds to a node to run Kubernetes on images with the Kubernetes layer.

  • How Kubernetes runs on a node


    The components of each type of node, the Kubernetes share and where the config comes from.

    Read

  • The control plane


    The static pods, the bootstrap, the joins of etcd and the add-ons the control plane applies.

    Read

  • Kubernetes networking


    How a node picks its addresses, dual stack, the VIP election, flannel and the ports of the control plane.

    Read

  • Kubernetes certificates


    The Kubernetes CAs and keys, the certificates of the control plane and the kubelets, and their rotation.

    Read

  • Kubernetes upgrades


    How a new Kubernetes version rolls through the control planes first.

    Read

Router layer

These pages describe what chalkos adds to a node of a router image to forward between its networks and filter what passes.

  • How a router works


    The router kinds, the Router document's kernel settings, the boot order and the guard of the management interfaces.

    Read

  • The router's firewall


    The one nftables table of a router: the protected rules, zones and policies, NAT, the reverse-path filter and the fallback ruleset.

    Read

  • BGP on a router


    FRR's config of the BGP kinds, the passwords as credentials, the reload, the boot order and the state chalkd reads.

    Read

  • VRFs on a router


    Why management stays in the default VRF, the units networkd gets, chalkos-vrf, FRR's instance per VRF, imported routes and the state chalkd reads.

    Read

  • Policy routing on a router


    The firewall's marks, the chain after the reverse-path filter, networkd's rules at priority 900 and the next hops' tables that fail closed.

    Read

  • NAT64 and DNS64 on a router


    Jool's instances of the NAT64 documents, the prefix's route, Unbound's rendered config with DNS64, the reloads and the state chalkd reads.

    Read