Write your first extension¶
This tutorial adds an extension to the image of the quick start's lab. The extension declares a
config kind, Hardware, which records who made a node's server and which model it is. The image
renders each node's Hardware document into an environment file, and a unit logs its contents.
At the end you have built the kind's schema, checked the nodes' config, tested the extension, run
it on the lab and changed it on a node. It takes about 15 minutes, most of it for the image build
and the lab.
The extension is examples/extensions/hardware.nix of the chalkos repository.
Before you begin¶
You need:
- the machine the quick start needs;
- a lab directory made from the
labtemplate, as the quick start makes it up to Generate the cluster's secrets: under git, withflake.lockandsecrets.json; - no lab named
labthat still runs. If the quick start's lab runs,chalklab destroyremoves it; - some Nix: NixOS modules and their options.
Run every command of this page in the lab directory, in the shell nix develop opens.
Write the extension¶
The output renders a file from a template. Create extensions/hardware.env.tmpl:
{{- range .documents.Hardware -}}
VENDOR={{ quote .spec.vendor }}
MODEL={{ quote .spec.model }}
ASSET_TAG={{ quote (default "" .spec.assetTag) }}
{{ end -}}
The template is Go's text/template. It reads the node's Hardware documents as
.documents.Hardware and writes one variable per field. quote writes a value as a
double-quoted string, and default gives the empty string for a missing asset tag.
Create extensions/hardware.nix, the module that declares the kind, the output and the unit:
{
chalkosLib,
config,
lib,
pkgs,
...
}:
{
chalkos.kinds.Hardware = {
group = "hardware.example.org";
version = "v1alpha1";
description = "Who made the node's server and which model it is.";
spec = {
vendor = lib.mkOption {
type = lib.types.nonEmptyStr;
example = "Supermicro";
description = "Vendor of the node's server.";
};
model = lib.mkOption {
type = lib.types.nonEmptyStr;
example = "SYS-E300-9D";
description = "Model of the node's server.";
};
assetTag = lib.mkOption {
type = lib.types.nullOr lib.types.nonEmptyStr;
default = null;
example = "HL-0042";
description = "Asset tag of the server, if it has one.";
};
};
};
# hardware.env, with VENDOR, MODEL and ASSET_TAG; empty on a node without a Hardware document.
chalkos.outputs.hardware = {
inputs = [ "Hardware" ];
render = chalkosLib.render.template ./hardware.env.tmpl;
};
# The unit reads the file when it starts, so a changed file restarts it.
chalkos.effects.hardware-info = chalkosLib.restartOn { outputs = [ "hardware" ]; } [
"hardware-info.service"
];
systemd.services.hardware-info = {
wantedBy = [ "multi-user.target" ];
serviceConfig = {
Type = "oneshot";
# Active after it ran, so chalkd's try-restart runs it again.
RemainAfterExit = true;
EnvironmentFile = "-${config.chalkos.outputs.hardware.dir}/hardware.env";
ExecStart = pkgs.writeShellScript "hardware-info" ''
echo "hardware: ''${VENDOR:-unknown} ''${MODEL:-unknown}''${ASSET_TAG:+, asset tag $ASSET_TAG}"
'';
};
};
}
The module has four parts:
chalkos.kinds.Hardwaredeclares the kind, in the grouphardware.example.org. Each option ofspecbecomes a field. An option without a default, such asvendor, is required.chalkos.outputs.hardwarerendershardware.envfrom the node'sHardwaredocuments with the template.chalkos.effects.hardware-inforestarts the unit when the output's files change.systemd.services.hardware-inforeads the rendered file as its environment and prints one line. The-before the path lets the unit start on a node without the file.
Add the module to the image node-kvm in flake.nix:
- modules = [ chalkos.nixosModules.kubernetes ];
+ modules = [
+ chalkos.nixosModules.kubernetes
+ ./extensions/hardware.nix
+ ];
Nix reads a flake from the files git tracks, so add the new files to git:
Look at the kind's schema¶
The image carries a JSON Schema for each kind it accepts. chalkctl and chalkd check every document against it. Build the schemas without building the image:
$ nix build .#nixosConfigurations.node-kvm.config.system.build.chalkosSchemas
$ ls result
chalkos.dev_v1alpha1_Host.json
chalkos.dev_v1alpha1_Secret.json
hardware.example.org_v1alpha1_Hardware.json
kubernetes.chalkos.dev_v1alpha1_Addon.json
...
time.chalkos.dev_v1alpha1_TimeSync.json
hardware.example.org_v1alpha1_Hardware.json is the new kind's. Its spec holds the three
options:
$ nix run nixpkgs#jq -- .properties.spec result/hardware.example.org_v1alpha1_Hardware.json
{
"additionalProperties": false,
"properties": {
"assetTag": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Asset tag of the server, if it has one.",
"examples": [
"HL-0042"
]
},
"model": {
"description": "Model of the node's server.",
"examples": [
"SYS-E300-9D"
],
"minLength": 1,
"type": "string"
},
"vendor": {
"description": "Vendor of the node's server.",
"examples": [
"Supermicro"
],
"minLength": 1,
"type": "string"
}
},
"required": [
"model",
"vendor"
],
"type": "object"
}
lib.types.nonEmptyStr became a string of at least one character. vendor and model are
required, and assetTag may be null. additionalProperties: false refuses a field the kind does
not declare.
Give w1 a Hardware document¶
Add this document to the end of nodes/w1.yaml, after a --- line:
apiVersion: hardware.example.org/v1alpha1
kind: Hardware
metadata: {name: hardware}
spec: {vendor: Supermicro, model: SYS-E300-9D}
cp1 gets no Hardware document, so its unit finds no file.
Check the config against the image¶
Build the image where the inventory points, and check each node's config against it with
chalkctl validate:
$ nix build .#node-kvm -o images/node-kvm
$ chalkctl validate
cp1: valid for the image node-kvm (node-kvm on kvm, root hash 5425995f5799), config cff86e2957830b9ec4a10a6f6966660695c5a332fca12103d59f79ab4c1ccc15
w1: valid for the image node-kvm (node-kvm on kvm, root hash 5425995f5799), config d8ddf99001390c55c88d34312a8ce7db6eee5f3d08a19f47e4b5fc50f90eaa55
Your root hash and config versions differ. To see the schema refuse a mistake, misspell model as
modle in nodes/w1.yaml and run the check again:
$ chalkctl validate
cp1: valid for the image node-kvm (node-kvm on kvm, root hash 5425995f5799), config cff86e2957830b9ec4a10a6f6966660695c5a332fca12103d59f79ab4c1ccc15
chalkctl: the config of 1 node is invalid:
node w1: Hardware "hardware": - at '/spec': additional properties 'modle' not allowed
- at '/spec': missing property 'model'
The refusal names the node, the document and the field. Change modle back to model.
Test the extension¶
A test gives the image a config and compares what it renders with golden files: files you checked once by eye. It runs in the Nix sandbox, without a node.
Create the test's config, extensions/hardware-examples/server.yaml:
apiVersion: hardware.example.org/v1alpha1
kind: Hardware
metadata: {name: hardware}
spec: {vendor: Supermicro, model: SYS-E300-9D, assetTag: HL-0042}
Declare the test in extensions/hardware.nix, after chalkos.outputs.hardware. It has no golden
files yet:
Add the file to git and build what each test of the image got:
$ git add extensions
$ nix build .#nixosConfigurations.node-kvm.config.system.build.chalkosTestResults
$ cat result/summary.txt
PASS chrony-empty
PASS chrony-servers
PASS hardware-server
PASS networkd-none
PASS networkd-static
PASS networkd-vlan
$ cat result/hardware-server/outputs/hardware/hardware.env
VENDOR="Supermicro"
MODEL="SYS-E300-9D"
ASSET_TAG="HL-0042"
The chrony and networkd tests are chalkos's own, which every image carries.
hardware.env holds what the unit should read, so keep it as the golden files:
mkdir -p extensions/tests/server
cp -r --no-preserve=mode result/hardware-server/outputs/hardware extensions/tests/server/hardware
git add extensions
Name the directory in the test, so every later build compares the rendered file with it:
# The image accepts the example and renders the hardware.env of the golden file from it.
chalkos.tests.hardware-server = {
config = ./hardware-examples/server.yaml;
outputs.hardware = ./tests/server/hardware;
};
Run the flake's checks, which run the image's tests:
$ nix flake check
evaluating flake...
...
checking flake output 'checks'...
checking derivation checks.x86_64-linux.node-kvm...
derivation evaluated to /nix/store/8qbr0jljylickbwk0h9kmxdzxr3fypzq-chalkos-tests.drv
...
running 3 flake checks...
building '/nix/store/yfskai0apdkv2ikjckxy016gds554p4z-chalkos-tests.json.drv'...
building '/nix/store/g1c3dr2wb0lwf5q4cafm9xxbkvldx2zr-chalkos-test-results.drv'...
building '/nix/store/8qbr0jljylickbwk0h9kmxdzxr3fypzq-chalkos-tests.drv'...
all checks passed!
A change to the template that alters hardware.env now fails the check, with a diff.
Run the extension on the lab¶
The tests change nothing in the image, so images/node-kvm is still current. Create the lab with
chalklab create, as the quick start does:
$ chalklab create --secrets secrets.json
creating the lab's Secure Boot keys in /home/alice/.local/state/chalklab/lab/keys
copying the image of cp1 from /home/alice/lab/images/node-kvm
copying the image of w1 from /home/alice/lab/images/node-kvm
starting cp1, w1
...
cp1 is bootstrapped; applied 19 objects
wrote /home/alice/.local/state/chalklab/lab/kubeconfig; its certificate is valid for 8760h0m0s
the lab lab runs cp1, w1; next:
export KUBECONFIG=/home/alice/.local/state/chalklab/lab/kubeconfig
export CHALKOSCONFIG=/home/alice/.local/state/chalklab/lab/chalkctl.json
export CHALKOSINVENTORY=/home/alice/.local/state/chalklab/lab/chalkos.yaml
...
Export the client file and the lab's inventory, as chalklab create printed, so chalkctl can
reach the nodes. Then read the unit's journal on each node
with chalkctl logs:
$ export CHALKOSCONFIG=~/.local/state/chalklab/lab/chalkctl.json
$ export CHALKOSINVENTORY=~/.local/state/chalklab/lab/chalkos.yaml
$ chalkctl logs w1 --unit=hardware-info.service
2026-11-16T10:54:36+00:00 w1 systemd[1]: Starting hardware-info.service...
2026-11-16T10:54:36+00:00 w1 9ci6jmda4j998yhh2wvridqpdga1jw23-hardware-info[508]: hardware: Supermicro SYS-E300-9D
2026-11-16T10:54:36+00:00 w1 systemd[1]: Finished hardware-info.service.
$ chalkctl logs cp1 --unit=hardware-info.service
2026-11-16T10:54:17+00:00 cp1 systemd[1]: Starting hardware-info.service...
2026-11-16T10:54:18+00:00 cp1 9ci6jmda4j998yhh2wvridqpdga1jw23-hardware-info[522]: hardware: unknown unknown
2026-11-16T10:54:18+00:00 cp1 systemd[1]: Finished hardware-info.service.
w1 logs its document. cp1 has none, so its hardware.env is empty and the unit prints its
fallback.
Change the document on w1¶
Give w1's server an asset tag. Change the document's spec in nodes/w1.yaml:
apiVersion: hardware.example.org/v1alpha1
kind: Hardware
metadata: {name: hardware}
spec: {vendor: Supermicro, model: SYS-E300-9D, assetTag: LAB-0001}
Check the config, then deliver it to w1 with
chalkctl config apply. Delivering config needs the secrets
file:
$ chalkctl validate
cp1: valid for the image node-kvm (node-kvm on kvm, root hash 5425995f5799), config cff86e2957830b9ec4a10a6f6966660695c5a332fca12103d59f79ab4c1ccc15
w1: valid for the image node-kvm (node-kvm on kvm, root hash 5425995f5799), config 9307d1da8a3a17a8e611ded2cdbdd577692950cc6eb963ce1712ecf656a25416
$ chalkctl config apply w1 --secrets secrets.json
w1: config 0 added, 0 removed, 1 changed
restarted hardware-info.service
w1 runs config 9307d1da8a3a17a8e611ded2cdbdd577692950cc6eb963ce1712ecf656a25416
The node rendered a new hardware.env, and the effect restarted the unit. No new image was
needed. The unit's journal shows the new line:
$ chalkctl logs w1 --unit=hardware-info.service
...
2026-11-16T10:55:02+00:00 w1 systemd[1]: Starting hardware-info.service...
2026-11-16T10:55:02+00:00 w1 9ci6jmda4j998yhh2wvridqpdga1jw23-hardware-info[1173]: hardware: Supermicro SYS-E300-9D, asset tag LAB-0001
2026-11-16T10:55:02+00:00 w1 systemd[1]: Finished hardware-info.service.
Check that it worked¶
chalkctl status lists the new output among the node's outputs, rendered:
$ chalkctl status w1
config 9307d1da8a3a17a8e611ded2cdbdd577692950cc6eb963ce1712ecf656a25416 (the inventory's)
previous config d8ddf99001390c55c88d34312a8ce7db6eee5f3d08a19f47e4b5fc50f90eaa55 (config rollback restores it)
platform kvm (the inventory's)
image 5425995f5799, booted from chalkos_1.efi
VOLUME DISK MOUNT POINT STATE
var system /var mounted
OUTPUT HASH STATE
chrony 0af9b0bd41ca rendered
hardware e81d9a3cbe14 rendered
networkd 195ac3c4ec51 rendered
...
Remove the lab with chalklab destroy when you are done:
What next¶
- Write a BGP extension is the fuller tutorial: two kinds, rules, a validator, secrets and a diagnostic.
- How an extension fits together shows where each part runs and which parts can refuse a delivery.
- Develop and debug an extension runs the checks from the fastest build to a node and lists the common errors.
- Declare a config kind starts the how-to pages, one task each.
- The extension API lists every option and
chalkosLibhelper.