arterialist/kube32 来源: https://github.com/arterialist/kube32 # kube32 CI (https://github.com/arterialist/kube32/actions/workflows/ci.yml) Docs (https://github.com/arterialist/kube32/actions/workflows/docs.yaml) kube32 是一个面向 ESP32-S3 微控制器的 Kubernetes 兼容控制面和 WebAssembly Pod 运行时。 kubectl 和 k9s 通过 Wi-Fi 或 USB 串口管理一组开发板集群。Pod 是由 wasm3 (https://github.com/wasm3/wasm3) 解释器执行的 WebAssembly 模块。 每块开发板都运行同一个固件镜像。 带有 PSRAM 的开发板充当控制面并运行本地 kubelet，而没有 PSRAM 的开发板则作为 worker 加入集群。 同一套源码可以构建 kube32-sim，即适用于 macOS 和 Linux 的宿主机模拟器。 ## 特性 - Kubernetes API 提供 Pod、Node、Namespace、Service、Endpoints、EndpointSlice、Ingress、Deployment、DaemonSet、Job、ConfigMap、Secret、Lease、Event 以及指标数据，供 kubectl 和 k9s 使用，支持 watch 流、Table 输出、OpenAPI v3 验证和日志跟踪。 - 基于 wasm3 (https://github.com/wasm3/wasm3) 的 WebAssembly Pod，提供 Rust、C 和 AssemblyScript 的 SDK 和模板，支持使用 k32_handle 的请求处理程序 ABI 或使用 app_main 的入口点 ABI，并支持可配置的内存限制和每次调用的 gas 预算。 - Service 路由、带主机和前缀规则的 HTTP Ingress、Server-Sent Events 流、通过 k32_resp_asset 和 StaticBundle 嵌入静态资源包，以及通过 k32_http_call 实现同步 Pod 间 HTTP 调用。 - 持久化对象存储，基于 CRC 校验的日志写入原始 flash 分区或 microSD 卡，支持通过 k32_fs_* 实现 persistentVolumeClaim Pod 卷，以及支持 kubectl logs --previous 的轮转容器日志。 - 外设访问通过能力防火墙按 Pod 进行隔离，涵盖 GPIO 引脚、ADC 通道、I2C 和 UART 总线、ST7789 显示屏、按键矩阵、I2S 扬声器和 microSD 存储。 - 容器生命周期管理，restartPolicy 支持 Always、OnFailure 或 Never，具备指数退避的 CrashLoopBackOff，以及针对 Wasm 陷阱、gas 耗尽和 OOMKilled 的不同退出码。 - 可选的 Bearer token 认证和在 6443 端口上的自动自签名 ECDSA P-256 TLS。 - 通过集群进行固件滚动更新：逐节点更新，SHA-256 校验，若镜像未能健康启动则由 bootloader 回滚。 - 通过 k32_event_emit 和 kube32.io/event-topics 实现发布/订阅事件，跨节点通过 ESP-NOW 和 UDP 7400 端口桥接。 - 多节点宿主机模拟器 kube32-sim 和 kube32-cli，用于构建、检查和通过网络或节点存储部署 Pod。 ## 硬件 | 角色 | 要求 | 参考开发板 | | — | — | — | | 控制面 | ESP32-S3、8 MB flash、2 MB 或更多四线 SPI PSRAM | 通用 ESP32-S3 开发板，配备 2 MB PSRAM | | Worker | 任意带有 8 MB flash 的 ESP32-S3 | M5Stack Cardputer，配备 ST7789 显示屏、键盘、扬声器和 microSD | 有关引脚分配和内存预算的详细信息，请参阅 docs/hardware-spec.md。 ## 快速开始 ### 模拟器 在 macOS 或 Linux 上构建并启动一个双节点集群： sh cmake -S . -B build && cmake --build build -j8 ./build/kube32-sim --ingress-port 8080 --pod-port 17000 在第二个终端中，配置 kubectl 并部署 echo 示例： sh 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 use-context kube32-sim kubectl get nodes kubectl apply -f examples/echo.yaml ### 开发板 使用 PlatformIO 构建固件并烧录到每块开发板： sh pio run -e esp32s3 bash scripts/flash.sh 921600 以 115200 波特率打开串口控制台，配置 Wi-Fi 和开发板配置： text K32_CMD:BOARD:cardputer # 仅 Cardputer worker K32_CMD:WIFI:: # 两块板均需 K32_CMD:AP:off # 控制面 K32_CMD:API: # worker 将 kubectl 指向控制面 IP 并应用清单文件： sh kubectl config set-cluster kube32 --server=http://:6443 kubectl config set-context kube32 --cluster=kube32 kubectl config use-context kube32 kubectl get nodes kubectl apply -f examples/echo.yaml 完整的设置说明和 TLS 配置请参阅 docs/quickstart.md。 ## 示例:Tessera Tessera 是一个由四个 WebAssembly Pod 组成的问题跟踪器，通过 Ingress 进行路由。tessera-web 和 tessera-api 运行在控制面上，用于提供 Web UI 和内存中的搜索索引。 tessera-db 和 tessera-hud 运行在 Cardputer worker 上，用于将记录持久化到 microSD 卡上的只追加日志，并驱动 LCD 和键盘（tessera-hud 默认静音；声音需要通过设置 HUD_SOUND=1 和扬声器能力来启用）。 生成示例数据集，将其上传到 worker 的 microSD 卡并部署： sh make -C apps/tessera dataset tools/kube32-cli push apps/tessera/build/card/kube32/volumes/tessera-db --node --path volumes/tessera-db kubectl apply -f examples/tessera.yaml 打开 http:/// 或模拟器上的 http://127.0.0.1:8080/，使用用户名 mara 和密码 demo 登录。 ## 文档 完整文档发布在 https://arterialist.github.io/kube32/。 - 快速开始 - 硬件规格 - 烧录和串口控制台 - 编写应用 Pod - 集群访问和认证 - Service、Ingress 和 Pod 间调用 - 存储和卷 - 外设 - 示例:Tessera - 架构概览 - Kubernetes API 覆盖范围 - CLI 和工具参考 ## 贡献 欢迎贡献。请阅读 CONTRIBUTING.md 了解构建说明、测试套件和编码规范，或在 GitHub (https://github.com/arterialist/kube32) 上提交 issue。 ## 安全 有关部署安全模型和私密报告漏洞的说明，请参阅 SECURITY.md。 ## 许可证 Apache License 2.0。详见 LICENSE。 third_party/wasm3 依据 MIT 许可证授权，详见 third_party/wasm3/LICENSE。