# 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