k3OS Declarative Provisioning: Cloud‑Init‑style config.yaml for Unattended Edge Nodes

Why manual provisioning is a pain

Deploying Kubernetes on edge or lab hardware usually means logging in, installing k3s, configuring networking, adding SSH keys, and then joining a cluster. A single typo can lock a node out of the fleet. k3OS solves this by treating the whole OS as a Kubernetes‑managed appliance, driven by a single declarative file.

What is k3OS and its config.yaml?

k3OS is a minimal, Kubernetes‑first Linux distribution that runs k3s as its only workload engine. Instead of a package manager, the OS state is expressed in a config.yaml file that follows a cloud‑init‑style schema. The file can specify:

• Hostname
• SSH authorized keys
• Network (static IP, DHCP, Wi‑Fi)
• k3s cluster parameters (server URL, node token)
• Optional systemd services or files

When the system boots, a built‑in cloud‑init process parses config.yaml and applies the desired state before starting k3s. The result is a fully unattended node that joins a cluster on first boot.

How to supply the configuration

k3OS accepts the config file in three common ways:

1. ISO boot – embed the file in the ISO image during image build.
2. PXE/HTTP boot – place the file on a web server and point the kernel command line with config_url=….
3. Kernel command line – inline the configuration with config=… or provide a URL.

All methods require root access on the machine that initiates the boot and, for PXE, a working DHCP and TFTP server.

Worked example: a node that joins a cluster, sets hostname, and adds an SSH key

Below is a minimal config.yaml that you could host at http://config.example.com/k3os.yaml and reference from the PXE boot loader.

hostname: "edge-node-01"
ssh_authorized_keys:
  - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... [contact removed]"

# Network – static IP on eth0
network:
  interfaces:
    eth0:
      dhcp4: false
      addresses:
        - 192.168.100.10/24
      gateway4: 192.168.100.1
      nameservers:
        addresses: [192.168.100.1, 8.8.8.8]

# k3s cluster parameters
k3s:
  token: ""
  server: "https://k3s-server.example.com:6443"
  node_labels:
    role: edge
  node_taints:
    - "edge=true:NoSchedule"

To test the configuration you can boot a k3OS ISO in a VM, point the kernel line to the URL, and wait for the node to appear in the cluster:

# On the k3s server
kubectl get nodes

# On the new node (once it boots)
cat /etc/hostname
cat /etc/ssh/authorized_keys

Check that the node shows the label role=edge and the taint edge=true:NoSchedule with:

kubectl get node edge-node-01 --show-labels
kubectl get node edge-node-01 -o jsonpath='{.spec.taints}'

Trade‑offs and limitations

• Archived project – Rancher stopped active development of k3OS around 2022. While the ISO and config schema remain usable, there are no security updates or new features.
• Version sensitivity – the config.yaml schema evolved across releases. Always match the schema to the exact k3OS version you run; a mismatched key can silently fail.
• Risk of drift – because the OS state is driven entirely by the YAML file, a wrong token or server URL can leave a fleet of nodes unable to join. Test the config on a single node before rolling out.
• No package manager – updates are performed by replacing the entire image or re‑provisioning. In-place package upgrades are not supported.

Actionable next steps

1. Choose a k3OS release that matches your test environment and download the ISO.
2. Host your config.yaml on a reliable HTTP server and verify accessibility from a test VM.
3. Boot the ISO with config_url=http://…/k3os.yaml and confirm the node joins the cluster.
4. If satisfied, move the configuration into a Git repository and use it as the single source of truth for future node deployments.
5. For new production workloads, consider actively maintained alternatives such as Talos or Elemental, which offer similar declarative models with ongoing support.

By treating the OS as a Kubernetes‑managed appliance, k3OS demonstrates how a simple, declarative file can turn a complex provisioning process into a repeatable, versioned workflow. Even though the project is archived, the concepts remain valuable for anyone exploring minimal, GitOps‑friendly edge operating systems.