Adolfo Delorenzo
e372df578b
Complete Phase 1 implementation of KubeSolo OS — an immutable, bootable Linux distribution built on Tiny Core Linux for running KubeSolo single-node Kubernetes. Build system: - Makefile with fetch, rootfs, initramfs, iso, disk-image targets - Dockerfile.builder for reproducible builds - Scripts to download Tiny Core, extract rootfs, inject KubeSolo, pack initramfs, and create bootable ISO/disk images Init system (10 POSIX sh stages): - Early mount (proc/sys/dev/cgroup2), cmdline parsing, persistent mount with bind-mounts, kernel module loading, sysctl, DHCP networking, hostname, clock sync, containerd prep, KubeSolo exec Shared libraries: - functions.sh (device wait, IP lookup, config helpers) - network.sh (static IP, config persistence, interface detection) - health.sh (containerd, API server, node readiness checks) - Emergency shell for boot failure debugging Testing: - QEMU boot test with serial log marker detection - K8s readiness test with kubectl verification - Persistence test (reboot + verify state survives) - Workload deployment test (nginx pod) - Local storage test (PVC + local-path provisioner) - Network policy test - Reusable run-vm.sh launcher Developer tools: - dev-vm.sh (interactive QEMU with port forwarding) - rebuild-initramfs.sh (fast iteration) - inject-ssh.sh (dropbear SSH for debugging) - extract-kernel-config.sh + kernel-audit.sh Documentation: - Full design document with architecture research - Boot flow documentation covering all 10 init stages - Cloud-init examples (DHCP, static IP, Portainer Edge, air-gapped) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
# KubeSolo OS
|
|
|
|
An immutable, bootable Linux distribution purpose-built for [KubeSolo](https://github.com/portainer/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
|
|
|
|
```bash
|
|
# 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 use `make 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](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
|