k3OS is a lightweight Linux distribution purpose-built to run Kubernetes clusters with minimal operating system maintenance overhead. The project is specifically designed to work exclusively with k3s, Rancher's lightweight Kubernetes distribution, and allows the entire operating system to be managed through kubectl once a cluster is bootstrapped. However, k3OS is no longer maintained and has been superseded by Elemental, with the project repository no longer accepting pull requests or issues.
The core design philosophy of k3OS centers on three primary goals: creating a minimal operating system for running Kubernetes through k3s, enabling upgrade and configuration management via kubectl, and providing versatile installation options for easy custom OS image creation. The distribution achieves this minimalism through a carefully structured filesystem architecture. The /etc directory contains only ephemeral configuration that reverts on reboot, with persistent changes requiring entries in the k3OS config.yaml file. The /usr directory is mounted as read-only and can only be modified by changing k3OS versions, though /usr/local is symlinked to the writable /var/local. The /k3os directory houses core operating system files including squashfs images and binaries for k3OS, k3s, and the Linux kernel, with the appropriate versions selected during boot. Persistent data belongs in /var, /usr/local, /home, or /opt.
The distribution repackages user-space binaries primarily from Alpine Linux while sourcing kernel code from Ubuntu 20.04 LTS, drawing inspiration and code from LinuxKit. Installation options are flexible and accommodate various deployment scenarios. Interactive installation boots from ISO and uses the k3os install command, while automated installation leverages kernel command-line parameters for unattended deployment. The distribution supports bootstrapped installation from any modern Linux distribution via install.sh, ISO remastering for custom configurations, takeover installation to convert existing Linux systems, and ARM overlay installation for custom ARMv7 and ARM64 devices. Live installation from ISO requires at least 2GB of RAM, while local disk installation needs only 1GB.
Configuration is handled through a single cloud-init style config.yaml file, with the /k3os/system/config.yaml reserved for system installation and bootstrap information, while /var/lib/rancher/k3os/config.yaml and config.d files are intended for runtime management. Kubernetes configuration is accomplished by configuring k3s through environment variables and k3s_args keys, with the write_files key enabling deployment of applications on boot by populating the /var/lib/rancher/k3s/server/manifests folder.
The repository is written in Go and classified across numerous infrastructure and edge computing categories including infrastructure automation, edge computing, minimal footprint, cloud-native deployment, single binary installation, systemd integration, ARM support, cloud compatibility, container management, lightweight Linux distribution, server management, IoT devices, configuration management, and Rancher integration. The project demonstrates particular relevance for IoT deployment scenarios and edge computing environments where minimal resource footprint and centralized Kubernetes-based management are critical requirements.
