kube32：在 ESP32 微控制器上重建 Kubernetes 控制平面與 WebAssembly Pod 執行環境

kube32 是適用於 ESP32-S3 微控制器的 Kubernetes 相容控制平面與 WebAssembly Pod 執行環境。

kubectl 與 k9s 透過 Wi-Fi 或 USB 序列埠管理板子叢集。Pod 是由 wasm3 解譯器執行的 WebAssembly 模組。每個板子都執行相同的韌體映像檔。具備 PSRAM 的板子做為控制平面並執行本機 kubelet，而不具備 PSRAM 的板子則做為 Worker 加入。相同的原始碼可用於建構適用於 macOS 與 Linux 的主機模擬器 kube32-sim。

功能

為 kubectl 與 k9s 提供 Kubernetes API 服務（包含 Pod、Node、Namespace、Service、Endpoints、EndpointSlice、Ingress、Deployment、DaemonSet、Job、ConfigMap、Secret、Lease、Event 及指標），支援 watch 串流、Table 輸出、OpenAPI v3 驗證與日誌追蹤。
wasm3 中的 WebAssembly Pod，提供適用於 Rust、C 與 AssemblyScript 的 SDK 與範本，可使用搭配 k32_handle 的要求處理常式（request-handler）ABI，或是搭配 app_main 的進入點（entry-point）ABI，並支援可設定的記憶體限制與每次呼叫的 gas 預算。
服務路由、具備主機與字首規則的 HTTP Ingress、Server-Sent Events 串流、透過 k32_resp_asset 與 StaticBundle 內嵌的靜態資產組合，以及透過 k32_http_call 進行的同步 Pod 對 Pod HTTP 呼叫。
由原始快閃記憶體分割區或 microSD 卡上經過 CRC 檢查的日誌支援的持續性物件儲存區，加上透過 k32_fs_* 提供的 persistentVolumeClaim Pod 磁碟區，以及用於 kubectl logs --previous 的輪替容器日誌。
周邊存取由涵蓋 GPIO 接腳、ADC 通道、I2C 與 UART 匯流排、ST7789 顯示器、按鍵矩陣、I2S 喇叭與 microSD 儲存空間的能力防火牆進行每個 Pod 的管控。
容器生命週期管理，將 restartPolicy 設為 Always、OnFailure 或 Never、具備指數退避的 CrashLoopBackOff（CrashLoopBackOff），以及針對 Wasm 攔截（trap）、gas 耗盡與 OOMKilled 的不同結束程式碼。
選用的 bearer-token 驗證，以及在連線埠 6443 上自動產生的自我簽署 ECDSA P-256 TLS。
透過叢集進行韌體滾動更新：一次一個節點、經過 SHA-256 檢查，當映像檔無法正常啟動時會進行開機載入程式（bootloader）回滾。
透過 k32_event_emit 與 kube32.io/event-topics 的發布/訂閱（pub/sub）事件，透過 ESP-NOW 與 UDP 連線埠 7400 在節點之間進行橋接。
多節點主機模擬器 kube32-sim 與 kube32-cli，用於透過網路或向節點儲存空間建構、檢查與部署 Pod。

硬體

角色	需求	參考板
控制平面	ESP32-S3、8 MB 快閃記憶體、2 MB 或更多 quad SPI PSRAM	具備 2 MB PSRAM 的通用 ESP32-S3 開發板
Worker	任何具備 8 MB 快閃記憶體的 ESP32-S3	具備 ST7789 顯示器、鍵盤、喇叭與 microSD 的 M5Stack Cardputer

請參閱 docs/hardware-spec.md 以取得接腳配置與記憶體預算。

快速入門

模擬器

在 macOS 或 Linux 上建構並啟動雙節點叢集：

cmake -S . -B build && cmake --build build -j8
./build/kube32-sim --ingress-port 8080 --pod-port 17000

在第二個終端機中，設定 kubectl 並部署 echo 範例：

export KUBECONFIG=$PWD/build/kubeconfig
kubectl config set-cluster kube32-sim --server=http://127.0.0.1:6443
kubectl config set-context kube32-sim --cluster=kube32-sim
kubectl config use-context kube32-sim
kubectl get nodes
kubectl apply -f examples/echo.yaml

板子

使用 PlatformIO 將韌體建構並燒錄到每個板子：

pio run -e esp32s3
bash scripts/flash.sh <serial-port> 921600

以 115200鮑率開啟序列主控臺，並佈建 Wi-Fi 與板子設定檔：

K32_CMD:BOARD:cardputer          # Cardputer worker only
K32_CMD:WIFI:<ssid>:<password>   # both boards
K32_CMD:AP:off                   # control plane
K32_CMD:API:<control-plane-ip>   # worker

將 kubectl 指向控制平面 IP 並套用資訊清單：

kubectl config set-cluster kube32 --server=http://<control-plane-ip>:6443
kubectl config set-context kube32 --cluster=kube32
kubectl config use-context kube32
kubectl get nodes
kubectl apply -f examples/echo.yaml

請參閱 docs/quickstart.md 以取得完整的設定指示與 TLS 設定。

範例：Tessera

Tessera 是一個由四個 WebAssembly Pod 組成、透過 Ingress 進行路由的問題追蹤器。tessera-web 與 tessera-api 在控制平面上執行，以提供網頁 UI 與記憶體內搜尋索引。tessera-db 與 tessera-hud 在 Cardputer Worker 上執行，將記錄持久化至 microSD 卡上的附加唯寫日誌，並驅動 LCD 與鍵盤（tessera-hud 預設為靜音；聲音需透過 HUD_SOUND=1 與喇叭能力手動啟用）。

產生範例資料集，將其上傳至 Worker 的 microSD 卡，並進行部署：

make -C apps/tessera dataset
tools/kube32-cli push apps/tessera/build/card/kube32/volumes/tessera-db --node <worker-node> --path volumes/tessera-db
kubectl apply -f examples/tessera.yaml

在模擬器上開啟 http://<control-plane-ip>/ 或 http://127.0.0.1:8080/，並以 mara 身分登入，密碼為 demo。

說明檔案

完整說明檔案發布於 https://arterialist.github.io/kube32/。

參與貢獻

歡迎各種形式的貢獻。請閱讀 CONTRIBUTING.md 以瞭解建置說明、測試套件與編碼準則，或者在 GitHub 上開啟 Issue。

安全性

請參閱 SECURITY.md 以瞭解部署安全性模型以及私下回報漏洞的說明。

授權條款

Apache License 2.0。請參閱 LICENSE。 third_party/wasm3 在 third_party/wasm3/LICENSE 中採用 MIT 授權。