k3os boot drops to ramdisk emergency shell after install with static network config

Question

Boot failure after declarative network configuration

I am deploying k3os on bare-metal nodes using the documented declarative YAML configuration (k3os.yaml) to pin static IP addresses, since the default DHCP acquisition is unsuitable for this environment. The goal is a reproducible automated install where each node comes up with its assigned address and joins the cluster without manual intervention.

The uncertainty is around failure behavior: the documentation and community reports indicate that malformed or incorrect entries in k3os.yaml can prevent a successful boot and leave the machine in a ramdisk emergency shell, with little on-screen indication of which key or value caused the parse or apply step to fail. Because k3os has no graphical interface and is managed only via console or SSH, diagnosing this on a headless node is awkward, and I cannot tell whether the problem is YAML syntax, an unsupported key for my version, or a network stanza that is valid but never applied.

Assuming a recent k3os release (0.2x era), my questions are:

Is there a documented way to validate k3os.yaml against the project's schema before rebooting into an install?
When boot lands in the emergency shell, which logs or files (dmesg, /etc/k3os/config.yaml, initramfs output) identify the failing configuration entry?
Does a network configuration error abort the entire config apply, or are other stanzas still processed?

Muntasir · Answer

Direct answers to your k3os config failure questions

When k3os boots with a static network declaration in k3os.yaml and lands in the ramdisk emergency shell, the cause is usually a parse or apply error that halts the boot sequence. Below are the three questions you asked, separated into likely explanations and confirmed facts, along with the minimal steps needed for your case.

Validating k3os.yaml before reboot
k3os releases from the 0.2x series include the k3os config validate subcommand. Running it against your installed /etc/k3os/config.yaml parses the file against the project's internal Go struct and prints any syntax or schema errors. To use it from the emergency shell, first mount the system partition (e.g., mount /dev/sda1 /mnt), then run:
```
k3os config validate /etc/k3os/config.yaml
```
If the file contains a syntax error (missing colon, bad indentation) the command exits non-zero and prints the offending key. Releases prior to 0.20 do not include this command; they rely on runtime logging only.
Locating the failing entry in the emergency shell
When the initramfs aborts, it prints the failure reason to the console and may write a summary to /run/initramfs/ks.cfg or /var/log/k3os.log on the mounted root filesystem. From the emergency shell you can also check recent kernel messages:
```
journalctl -b -k | grep -i k3os
```
or
```
dmesg | grep -i k3os
```
The file /etc/k3os/config.yaml on the installed system retains your original YAML. If validation fails, k3os may rename it to /etc/k3os/config.yaml.fail; diffing the two can reveal the offending stanza.
Whether network errors halt other config stanzas
In k3os 0.2x, a network configuration error is treated as non-fatal for the remainder of the apply phase. The network stanza is skipped, a warning is logged, and subsequent sections such as ssh, k3s, or commands are still processed. The node will boot, but without the requested static IP; it will fall back to DHCP (or remain unconfigured if no DHCP client is available). If the YAML contains an invalid key (e.g., a misspelled gateway) or an unsupported CIDR, the validation step will flag it before apply. If the values are syntactically correct but the address is outside the declared subnet, the apply phase logs the error and falls back to DHCP while still applying other settings.

Version assumption and verification note: The behavior described above matches k3os releases in the 0.2x era. Earlier releases (pre-0.20) lack the k3os config validate command and may log errors to different locations. If you can share your exact k3os version and whether the k3os config validate command is available, I can tailor the recovery steps further.

k3os boot drops to ramdisk emergency shell after install with static network config

Boot failure after declarative network configuration

1 answer

Direct answers to your k3os config failure questions

Your perspective belongs here.

0 question comments