k3s-device: Multi-Board Embedded Kubelet Platform

Transform embedded devices into Kubernetes worker nodes with device-agnostic infrastructure and board-specific firmware implementations.

Vision

A unified platform that enables GitOps-style device provisioning where the Kubernetes cluster itself manages physical device setup, configuration, and workload deployment across multiple embedded architectures.

Supported Implementations

Board	Architecture	Language	Status
Raspberry Pi Pico W	ARM Cortex-M0+	C	✅ Reference Implementation
ESP32	Xtensa LX6	C	🔜 Planned
MicroPython	Various	Python	🔜 Planned
Arduino	Various	C++	🔜 Planned

Quick Start

1. Environment Setup

# Clone the repository
git clone https://github.com/mak3r/k3s-device.git
cd k3s-device

# Run interactive setup
./setup-env.sh

# This generates CLAUDE.md with your environment configuration

2. Choose Your Implementation

For Raspberry Pi Pico W:

cd implementations/rp2040-pico-c
# See implementation-specific README for build instructions

3. Deploy Infrastructure

# Deploy device-agnostic k8s infrastructure
kubectl apply -f infrastructure/manifests/

# Verify proxy is running
kubectl get pods -n kube-system -l app=pico-proxy

Platform Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                        │
│  ┌────────────────┐  ┌──────────────┐  ┌─────────────────┐ │
│  │ Infrastructure │  │ ECI Library  │  │ Provisioning    │ │
│  │ (Proxy, etc.)  │  │ (Workloads)  │  │ (Device Setup)  │ │
│  └────────────────┘  └──────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
   │ Pico W  │       │ ESP32   │       │ Arduino │
   │ (C SDK) │       │ (C/IDF) │       │ (C++)   │
   └─────────┘       └─────────┘       └─────────┘

Repository Structure

• implementations/ - Board Support Packages (BSPs) with firmware + provisioning
• infrastructure/ - Device-agnostic k8s resources (proxy, operators)
• eci-library/ - Embedded Container Images by architecture
• specs/ - Kubelet protocol, API contracts, porting guides
• docs/ - Platform documentation and contribution guides

Key Features

• Multi-Board Support: Extensible architecture for diverse microcontrollers
• Reference Implementation: Complete RP2040 Pico W BSP as template
• HTTP-Only Design: TLS termination at proxy (ideal for constrained devices)
• ECI Library: Architecture-specific embedded workloads
• GitOps Provisioning: Cluster-managed device flashing and configuration

Adding a New Board

See the comprehensive Porting Guide for step-by-step instructions on adding support for new hardware platforms.

Documentation

• Platform Architecture
• Kubelet Requirements
• ECI Format Specification
• Contributing Guide

Dependencies

External dependencies are documented but not included:

• Raspberry Pi Pico SDK (for Pico implementations)
• k3s cluster (local or remote)

License

Apache License 2.0 - See LICENSE for details.

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Started as: Single-board project (k3s-pico-node) Evolved into: Multi-board embedded kubelet platform