Boot and the image¶
This page is for operators and image authors who read a node's ESP or boot logs, or decide whether a change needs a new image or a config delivery. It lists the rules by which systemd-boot picks the UKI a node boots, the units that do chalkos's work at every boot, and what an image fixes when it is built and what reaches a node in its config. Boot, health and rollback explains the boot.
systemd-boot sort rules¶
systemd-boot lists the UKIs in /EFI/Linux on the ESP and boots the first entry of this order
whose tries are not used up. Each rule decides only between entries that the rules above it leave
equal.
| Rule | Order | On a chalkos node |
|---|---|---|
| Tries left | Entries with tries left, or without a counter, first; used-up entries last | A new image's entry is passed over once its tries are used up, so the previous generation boots |
| Image ID | IMAGE_ID, or else ID, lowest first |
Every chalkos UKI has IMAGE_ID=chalkos. A UKI of another image whose ID sorts before it, such as IMAGE_ID=alpine, boots before every chalkos entry |
IMAGE_VERSION |
Highest first | Empty on every chalkos image, so it decides nothing |
| File name | Highest first, numbers compared as numbers | chalkos_<generation>.efi, so chalkos_10.efi comes before chalkos_9.efi and the entry installed last boots first, whether its image is newer or older |
The image and an install write generation 1, and each upgrade writes the generation above the
highest on the ESP. An entry being counted carries its tries in its name, as
chalkos_<generation>+<tries>.efi and then chalkos_<generation>+<left>-<used>.efi. chalkd sets
no EFI variable to choose the entry, so the order is systemd-boot's own. chalkos never writes UKIs
of other image IDs to the ESP and leaves those placed there alone.
Boot units¶
These units do chalkos's work when an installed node boots. The second column says when each runs.
| Unit | Runs | Command | What it does |
|---|---|---|---|
chalkos-state.service |
in the initrd | chalkos-storage state |
Unlocks and mounts STATE, with the TPM or with the second key the console asks for |
chalkos-storage.service |
in the initrd | chalkos-storage initrd |
Creates the volumes recorded on STATE and mounts VAR |
chalkos-config.service |
before networkd | chalkd load-config |
Ends a config's trial that is still open, then applies the config on STATE: the hostname, the documents in /run/chalkos/config, the secrets the granted units read, and the outputs, networkd's units and chrony's time servers among them |
chalkd.service |
after the network | chalkd serve |
Serves the node API and carries out its requests |
chalkos-console.service |
after chalkd and the volumes' passphrase prompts, while chalkos.console.enable is true |
chalkos-console |
Shows the console on tty1 in place of the getty |
chalkos-kubernetes.service |
on images with Kubernetes, once the network is online | chalkd kubernetes prepare |
Waits for the node's addresses and prepares its Kubernetes certificates, kubeconfigs and kubelet flags |
chalkos-health.service |
only on a boot that systemd-boot counts | chalkd health |
Decides whether a new image is healthy |
The installer runs none of chalkos-state.service, chalkos-storage.service and
chalkos-config.service.
What an image fixes and what config delivers¶
The left column changes only with a new image and an upgrade. The right column changes with a config delivery, without a reboot.
| Fixed when the image is built | Delivered at runtime, in the config |
|---|---|
| Kernel, kernel modules and initrd | Hostname, in Host, and whether the node is a control plane or a worker, in Node |
| NixOS services and the image's modules, the services of extensions among them | systemd-networkd units, in Network, NetDev and Link |
| Kubernetes release, the images of its components and the CNI provider | The cluster's endpoint and its Kubernetes settings: ranges, VIP, extra flags and addons, in Cluster, Flannel and Addon, and registry mirrors in Mirror |
The OS CA for maintenance mode, from the osCA argument of mkImages |
The kubelet's addresses, labels and taints, in Node too |
| Partition sizes of the system region | Storage: system disk, VAR, volumes and encryption, in SystemDisk and Volume |
| Boot tries and health timeout | Time servers, in TimeSync |
| The config kinds the image accepts and their schemas | Documents of the kinds extensions declare, and the Secrets they reference |
Sources: systemd-boot's sort order, pkg/esp, modules/node/base/storage.nix, modules/node/chalkd.nix, modules/node/kubernetes,
modules/node/upgrade.nix, modules/installer/default.nix, lib/images-arguments.nix and
modules/node/kinds.