Skip to content

Build images

These pages are for image authors who build a cluster's images in Nix with chalkos.lib.mkImages. They assume some Nix and NixOS modules, and no earlier knowledge of chalkos.

Start here: Your first image flake, then Images and platforms, then Add software, drivers and kernel modules. Every later page builds on the flake from these three. Write your first extension then adds a config kind and a unit that reads it, on the lab of the quick start.

How an extension fits together

An extension is a NixOS module that adds config kinds and the parts that act on their documents. The diagram follows a node's YAML from a delivery to the units that read it.

flowchart LR
    yaml["YAML documents"] --> schema["Kind schema"]
    schema --> rules["Change rules"]
    facts["Facts"] -.->|read by| rules
    rules --> validators["Validators"]
    validators --> outputs["Outputs: render and check"]
    outputs --> swap["Config slot and dir swap"]
    swap --> effects["Effects"]
    effects -->|restart, reload| units["Units"]
    swap --> grants["Grants and credentials"]
    grants -->|files, credentials| units
    diag["Diagnostics"] -.->|chalkctl node diag| units
    tests["chalkos.tests in the Nix sandbox"] -.->|run the same checks| schema

The schema, the change rules, the validators and the outputs can each refuse a delivery. The node then keeps the config it runs. Once all four pass, chalkd writes the config slot, swaps the documents and rendered files in, and takes the effects. Diagnostics stand apart: an operator runs them on demand. The tests run the same checks as a delivery, without a node.

Each part is an option of the image's modules. A part that chalkctl runs refuses a mistake before anything reaches the node.

Option Where it runs Can refuse a delivery Page
chalkos.kinds chalkctl and the node, against the kind's schema yes Declare a config kind
chalkos.kinds.<name>.rules, specRules chalkctl, for the rules that read no facts; the node, for every rule yes Guard changes with rules and facts
chalkos.facts the node, when a rule or an effect's when reads the fact no Guard changes with rules and facts
chalkos.validators the node; chalkctl runs only the router layer's router yes Validate config with a program
chalkos.outputs the node, before a delivery changes anything, and at boot yes Render config files
chalkos.effects the node, once a delivery is applied no React to changes
systemd.services.<unit>.chalkos.kinds the node, for the unit the grant names no Read config in a service, Pass secrets to a service
chalkos.diagnostics the node, on chalkctl node diag no Add a diagnostic
chalkos.tests the build, in the Nix sandbox, by nix flake check no; a failing test fails the check Test an extension

The fast loop

Three builds check an extension without a node. Run them in the image flake, with <image> the name of an image of its mkImages:

# The kinds' JSON Schemas, as chalkctl checks documents against them.
nix build .#nixosConfigurations.<image>.config.system.build.chalkosSchemas
# What each test rendered and refused; -L prints the errors of renderers and checks.
nix build -L .#nixosConfigurations.<image>.config.system.build.chalkosTestResults
# Every image's tests, compared with what they expect.
nix flake check

Develop and debug an extension runs the whole loop, from these builds to a node, and lists the common errors.

Build

These pages build an image a node can install: the flake, its images and platforms, and the software it carries.

  • Your first image flake


    Write a flake that builds a cluster's image with mkImages, into the directory the inventory names.

    Read

  • Images and platforms


    Build images for nodes that run other software or other machines, and set the order of their modules.

    Read

  • Add software, drivers and kernel modules


    Add packages, services, kernel modules, firmware and debug tools within an appliance's limits.

    Read

Configure services

These pages give the services in an image their configuration, in the order an extension grows: a config kind for each node's YAML, the files a unit reads, the tests that check them, the effects of a change, its secrets and the checks that refuse a config a node cannot run.

  • Write your first extension


    A tutorial of about 15 minutes: add a config kind, a rendered file, a test and a unit to the quick start's lab, then change the config on a node.

    Follow

  • Develop and debug an extension


    Check an extension from the fastest build to a node, find the cause of an evaluation error and fix common errors.

    Read

  • Declare a config kind


    Declare a config kind in a NixOS module, so each node's YAML carries values the image checks.

    Read

  • Read config in a service


    Grant a unit the config kinds it reads, and read their documents as files or with chalkcfg.

    Read

  • Render config files


    Render a service's config file from the node's documents, checked before a delivery changes anything.

    Read

  • Test an extension


    Check what an image renders, refuses and reloads for a config, with tests that nix flake check runs.

    Read

  • React to changes


    Restart, reload or run a command when a delivery changes an output, a kind's documents or a condition.

    Read

  • Pass secrets to a service


    Reference a Secret from a field of your kind, so a granted unit gets its value as a systemd credential.

    Read

  • Validate config with a program


    Refuse a node's config with a program of your image, for what the kind's schema and rules cannot check.

    Read

  • Guard changes with rules and facts


    Refuse a config change a node cannot make, with CEL rules on your kind and facts about the node.

    Read

Diagnose

This page gives operators a way to look into a service on a node.

  • Add a diagnostic


    Declare a read-only command that operators run on a node with chalkctl node diag.

    Read

Ship

These pages take an image to the nodes: the installer, signing for Secure Boot, publishing to a registry, testing and rolling out an upgrade, and changing a kind between images.

  • Customise the installer


    Give the installer static addresses, VLANs, bonds, drivers or firmware.

    Read

  • Sign images for Secure Boot


    An optional step: create Secure Boot keys and enrol them, sign a copy of each image and the installer, and name the signed copy in the inventory.

    Read

  • Publish images to a registry


    Build an image as an OCI layout, sign it if the nodes need it, push it and name its digest in the inventory.

    Read

  • Test and roll out an image


    Check an image and the nodes' config, upgrade the nodes, and confirm their outputs and services.

    Read

  • Change a kind incompatibly


    Give a kind a new version, move the nodes' documents to it with an upgrade, and rename or remove a kind.

    Read