Adolfo Delorenzo
39732488ef
Build a custom Tiny Core 17.0 kernel (6.18.2) with missing configs that the stock kernel lacks for container workloads: - CONFIG_CGROUP_BPF=y (cgroup v2 device control via BPF) - CONFIG_DEVTMPFS=y (auto-create /dev device nodes) - CONFIG_DEVTMPFS_MOUNT=y (auto-mount devtmpfs) - CONFIG_MEMCG=y (memory cgroup controller for memory.max) - CONFIG_CFS_BANDWIDTH=y (CPU bandwidth throttling for cpu.max) Also strips unnecessary subsystems (sound, GPU, wireless, Bluetooth, KVM, etc.) for minimal footprint on a headless K8s edge appliance. Init system fixes for successful boot-to-running-pods: - Add switch_root in init.sh to escape initramfs (runc pivot_root) - Add mountpoint guards in 00-early-mount.sh (skip if already mounted) - Create essential device nodes after switch_root (kmsg, console, etc.) - Enable cgroup v2 controller delegation with init process isolation - Mount BPF filesystem for cgroup v2 device control - Add mknod fallback from sysfs in 20-persistent-mount.sh for /dev/vda - Move KubeSolo binary to /usr/bin (avoid /usr/local bind mount hiding) - Generate /etc/machine-id in 60-hostname.sh (kubelet requires it) - Pre-initialize iptables tables before kube-proxy starts - Add nft_reject, nft_fib, xt_nfacct to kernel modules list Build system changes: - New build-kernel.sh script for custom kernel compilation - Dockerfile.builder adds kernel build deps (flex, bison, libelf, etc.) - Selective kernel module install (only modules.list + transitive deps) - Install iptables-nft (xtables-nft-multi) + shared libs in rootfs Tested: ISO boots in QEMU, node reaches Ready in ~35s, CoreDNS and local-path-provisioner pods start and run successfully. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
KubeSolo OS
An immutable, bootable Linux distribution purpose-built for KubeSolo — Portainer's ultra-lightweight single-node Kubernetes.
Status: Phase 1 — Proof of Concept
What is this?
KubeSolo OS combines Tiny Core Linux (~11 MB) with KubeSolo (single-binary Kubernetes) to create an appliance-like K8s node that:
- Boots to a functional Kubernetes cluster in ~30 seconds
- Runs entirely from RAM with a read-only SquashFS root
- Persists K8s state across reboots via a dedicated data partition
- Targets < 100 MB total image size (OS + K8s)
- Requires no SSH, no package manager, no writable system files
- Supports atomic A/B updates with automatic rollback (Phase 3)
Target use cases: IoT/IIoT edge, air-gapped deployments, single-node K8s appliances, kiosk/POS systems, resource-constrained hardware.
Quick Start
# Fetch Tiny Core ISO + KubeSolo binary
make fetch
# Build bootable ISO
make iso
# Test in QEMU
make dev-vm
Requirements
Build host:
- Linux x86_64 with root/sudo (for loop mounts)
- Tools:
cpio,gzip,wget,curl,syslinux(or usemake docker-build)
Runtime:
- x86_64 hardware or VM
- 512 MB RAM minimum (1 GB+ recommended)
- 8 GB disk (for persistent data partition)
Architecture
Boot Media → Kernel + Initramfs (kubesolo-os.gz)
│
├── SquashFS root (read-only, in RAM)
├── Persistent data partition (ext4, bind-mounted)
│ ├── /var/lib/kubesolo (K8s state, certs, SQLite)
│ ├── /var/lib/containerd (container images)
│ └── /etc/kubesolo (node configuration)
├── Custom init (POSIX sh, staged boot)
└── KubeSolo (exec replaces init as PID 1)
See docs/design/kubesolo-os-design.md for the full architecture document.
Project Structure
├── CLAUDE.md # AI-assisted development instructions
├── Makefile # Build orchestration
├── build/ # Build scripts, configs, rootfs overlays
├── init/ # Custom init system (POSIX sh)
├── update/ # Atomic update agent (Go, Phase 3)
├── cloud-init/ # First-boot configuration (Phase 2)
├── test/ # QEMU-based automated tests
├── hack/ # Developer utilities
└── docs/ # Design documents
Roadmap
| Phase | Scope | Status |
|---|---|---|
| 1 | PoC: boot Tiny Core + KubeSolo, verify K8s | 🚧 In Progress |
| 2 | Persistent storage, cloud-init, networking | Planned |
| 3 | A/B atomic updates, GRUB, rollback | Planned |
| 4 | Production hardening, signing, Portainer Edge | Planned |
| 5 | OCI distribution, ARM64, fleet management | Planned |
License
TBD