feat: initial Phase 1 PoC scaffolding for KubeSolo OS

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>

build/rootfs/etc/kubesolo/defaults.yaml

@@ -0,0 +1,22 @@
+# KubeSolo OS — Default KubeSolo Configuration
+# These defaults are used when no cloud-init or persistent config is found.
+# Overridden by: /etc/kubesolo/config.yaml (persistent) or cloud-init
+
+# Data directory for K8s state (certs, etcd/sqlite, manifests)
+data-dir: /var/lib/kubesolo
+
+# Enable local-path provisioner for PersistentVolumeClaims
+local-storage: true
+
+# API server will listen on all interfaces
+bind-address: 0.0.0.0
+
+# Cluster CIDR ranges
+cluster-cidr: 10.42.0.0/16
+service-cidr: 10.43.0.0/16
+
+# Disable components not needed for single-node
+# (KubeSolo may handle this internally)
+# disable:
+#   - traefik
+#   - servicelb

build/rootfs/etc/sysctl.d/k8s.conf

@@ -0,0 +1,17 @@
+# Kubernetes networking requirements
+net.bridge.bridge-nf-call-iptables = 1
+net.bridge.bridge-nf-call-ip6tables = 1
+net.ipv4.ip_forward = 1
+
+# inotify limits (containerd + kubelet watch requirements)
+fs.inotify.max_user_instances = 1024
+fs.inotify.max_user_watches = 524288
+
+# Connection tracking (kube-proxy)
+net.netfilter.nf_conntrack_max = 131072
+
+# File descriptor limits
+fs.file-max = 1048576
+
+# Disable swap (K8s requirement — though we have no swap anyway)
+vm.swappiness = 0

build/rootfs/usr/lib/kubesolo-os/health.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+# health.sh — Health check functions for KubeSolo OS
+# Used by init health monitoring and update agent rollback logic
+# POSIX sh only.
+
+KUBECONFIG_PATH="/var/lib/kubesolo/pki/admin/admin.kubeconfig"
+
+# Check if containerd socket is responding
+check_containerd() {
+    [ -S /run/containerd/containerd.sock ] || return 1
+    # If ctr is available, try listing containers
+    if command -v ctr >/dev/null 2>&1; then
+        ctr --connect-timeout 5s version >/dev/null 2>&1
+    else
+        return 0  # socket exists, assume ok
+    fi
+}
+
+# Check if the K8s API server is responding
+check_apiserver() {
+    kubeconfig="${1:-$KUBECONFIG_PATH}"
+    if [ ! -f "$kubeconfig" ]; then
+        return 1
+    fi
+    if command -v kubectl >/dev/null 2>&1; then
+        kubectl --kubeconfig="$kubeconfig" get --raw /healthz >/dev/null 2>&1
+    elif command -v curl >/dev/null 2>&1; then
+        # Fallback: direct API call
+        server=$(sed -n 's/.*server: *//p' "$kubeconfig" 2>/dev/null | head -1)
+        [ -n "$server" ] && curl -sk "${server}/healthz" >/dev/null 2>&1
+    else
+        return 1
+    fi
+}
+
+# Check if the node has reached Ready status
+check_node_ready() {
+    kubeconfig="${1:-$KUBECONFIG_PATH}"
+    [ -f "$kubeconfig" ] || return 1
+    command -v kubectl >/dev/null 2>&1 || return 1
+    kubectl --kubeconfig="$kubeconfig" get nodes 2>/dev/null | grep -q "Ready"
+}
+
+# Combined health check — returns 0 only if all components are healthy
+check_health() {
+    check_containerd || return 1
+    check_apiserver || return 1
+    check_node_ready || return 1
+    return 0
+}
+
+# Wait for system to become healthy with timeout
+wait_for_healthy() {
+    timeout="${1:-300}"
+    interval="${2:-5}"
+    elapsed=0
+    while [ "$elapsed" -lt "$timeout" ]; do
+        check_health && return 0
+        sleep "$interval"
+        elapsed=$((elapsed + interval))
+    done
+    return 1
+}

build/rootfs/usr/lib/kubesolo-os/network.sh

@@ -0,0 +1,80 @@
+#!/bin/sh
+# network.sh — Network configuration helpers for KubeSolo OS init
+# Sourced by init stages. POSIX sh only.
+
+# Configure a static IP address on an interface
+# Usage: static_ip <iface> <ip/prefix> <gateway> [dns1] [dns2]
+static_ip() {
+    iface="$1" addr="$2" gw="$3" dns1="${4:-}" dns2="${5:-}"
+
+    ip link set "$iface" up
+    ip addr add "$addr" dev "$iface"
+    ip route add default via "$gw" dev "$iface"
+
+    # Write resolv.conf
+    : > /etc/resolv.conf
+    [ -n "$dns1" ] && echo "nameserver $dns1" >> /etc/resolv.conf
+    [ -n "$dns2" ] && echo "nameserver $dns2" >> /etc/resolv.conf
+}
+
+# Save current network configuration for persistence across reboots
+# Writes a shell script that can be sourced to restore networking
+save_network_config() {
+    dest="${1:-/mnt/data/network/interfaces.sh}"
+    mkdir -p "$(dirname "$dest")"
+
+    iface=""
+    for d in /sys/class/net/*; do
+        name="$(basename "$d")"
+        case "$name" in lo|docker*|veth*|br*|cni*) continue ;; esac
+        iface="$name"
+        break
+    done
+    [ -z "$iface" ] && return 1
+
+    addr=$(ip -4 addr show "$iface" | sed -n 's/.*inet \([0-9./]*\).*/\1/p' | head -1)
+    gw=$(ip route show default 2>/dev/null | sed -n 's/default via \([0-9.]*\).*/\1/p' | head -1)
+
+    cat > "$dest" << SCRIPT
+#!/bin/sh
+# Auto-saved network config — generated by KubeSolo OS
+ip link set $iface up
+ip addr add $addr dev $iface
+ip route add default via $gw dev $iface
+SCRIPT
+
+    # Append DNS if resolv.conf has entries
+    if [ -f /etc/resolv.conf ]; then
+        echo ": > /etc/resolv.conf" >> "$dest"
+        sed -n 's/^nameserver \(.*\)/echo "nameserver \1" >> \/etc\/resolv.conf/p' \
+            /etc/resolv.conf >> "$dest"
+    fi
+
+    chmod +x "$dest"
+}
+
+# Get the primary network interface name
+get_primary_iface() {
+    for d in /sys/class/net/*; do
+        name="$(basename "$d")"
+        case "$name" in lo|docker*|veth*|br*|cni*) continue ;; esac
+        echo "$name"
+        return 0
+    done
+    return 1
+}
+
+# Wait for link on an interface
+wait_for_link() {
+    iface="$1"
+    timeout="${2:-15}"
+    i=0
+    while [ "$i" -lt "$timeout" ]; do
+        if ip link show "$iface" 2>/dev/null | grep -q 'state UP'; then
+            return 0
+        fi
+        sleep 1
+        i=$((i + 1))
+    done
+    return 1
+}