kubesolo

Ultra-lightweight, OCI-compliant, single-node Kubernetes built for constrained environments. No clustering. No etcd. Just what you need to run real workloads on real hardware.

Overview

KubeSolo is designed for devices at the farthest layer of the network, such as IoT, IIoT, and embedded systems. The image illustrates the three main layers of modern distributed infrastructure:

1. Cloud (Data Centers) Scale: Thousands of nodes Examples: Amazon EKS, Google Kubernetes Engine, VMware Tanzu, Sidero Purpose: Centralized, large-scale compute and storage
2. FOG (Distributed Nodes) Scale: Millions of nodes Examples: K3s, MicroK8s, Sidero, K0S Purpose: Distributed compute closer to the edge, often for latency-sensitive or regional workloads
3. Edge (Devices) Scale: Billions of devices Example: KubeSolo Purpose: Ultra-lightweight Kubernetes for resource-constrained environments (IoT gateways, industrial controllers, smart devices, etc.) KubeSolo sits at the very bottom of this stack, providing a simple, single-node Kubernetes experience for the edge, where minimal resources and offline operation are critical.

What is this?

KubeSolo is a production-ready single-node Kubernetes distribution with the following changes:

• It is packaged as a single binary
• It uses SQLite (via Kine) as the default storage backend
• It wraps Kubernetes and other components in a single, simple launcher
• It is secure by default with reasonable defaults for lightweight environments
• It has minimal OS dependencies (just a sane kernel and cgroup mounts needed)
• It eliminates the need for complex multi-node setup by providing a single-node solution

KubeSolo bundles the following technologies together into a single cohesive distribution:

• containerd & runc for container runtime
• CoreDNS for DNS resolution
• Kine for SQLite-based storage

What's with the name?

KubeSolo is designed to be a single-node Kubernetes distribution, hence the "Solo" in the name. It's meant to be simple, lightweight, and perfect for development, testing, or small production workloads that don't require the complexity of a multi-node cluster.

Is this a fork?

No, it's a distribution. A fork implies continued divergence from the original. This is not KubeSolo's goal or practice. KubeSolo explicitly intends not to change any core Kubernetes functionality. We seek to remain as close to upstream Kubernetes as possible by leveraging the k3s forked Kubernetes. However, we maintain a small set of patches important to KubeSolo's use case and deployment model.

How is this lightweight or smaller than upstream Kubernetes?

There are three major ways that KubeSolo is lighter weight than upstream Kubernetes:

• The memory footprint to run is smaller
• The binary, which contains all the non-containerized components needed to run a cluster, is smaller
• The Kubernetes Scheduler does not exist, instead, it is replaced by a custom Webhook called NodeSetter

The memory footprint is reduced primarily by:

• Running many components inside of a single process
• Using SQLite instead of etcd
• Optimizing resource limits for single-node usage
• Replacing the Kubernetes Scheduler with NodeSetter

Why is the binary size big compared to other distributions?

KubeSolo is designed specifically for IoT or IIoT devices, such as embedded systems, which typically lack internet connectivity. To address this limitation, KubeSolo is equipped with all the necessary components to ensure it is offline ready.

Getting Started

Quick Install

Warning

Ensure that no container engine (e.g., Docker, Podman, containerd) is installed or active on the target system prior to proceeding. This includes any background services or residual installations that could interfere with KubeSolo networking.

# Download and install KubeSolo
curl -sfL https://get.kubesolo.io | sudo sh -

The installer automatically detects your system and downloads the appropriate binary:

• glibc systems (Ubuntu, CentOS, Debian, etc.): Downloads standard binary
• musl systems (Alpine Linux): Downloads musl-compatible binary

A kubeconfig file is written to /var/lib/kubesolo/pki/admin/admin.kubeconfig and the service is automatically started.

Note: If you're running KubeSolo on a device with less than 512MB of RAM, it's strongly advised to interact with KubeSolo using the kubectl command-line tool installed externally.

Advanced Installation

For detailed installation instructions including support for industrial devices, embedded systems, different init systems, and custom configurations, see the Installation Guide.

The installation guide covers:

• Universal installer with automatic init system detection
• Minimal installer for constrained environments
• Service management across different platforms
• Industrial device considerations (read-only filesystems, limited storage, air-gapped installations)
• Architecture-specific installations

Flags

KubeSolo supports the following command-line flags:

Flag	Environment Variable	Description	Default
--path	KUBESOLO_PATH	Path to the directory containing the kubesolo configuration files	/var/lib/kubesolo
--apiserver-extra-sans	KUBESOLO_APISERVER_EXTRA_SANS	A comma-separated list of additional Subject Alternative Names (SANs) to include in the API server's TLS certificate. These SANs can be IP addresses or DNS names (e.g., 10.0.0.4,kubesolo.local)	""
--portainer-edge-id	KUBESOLO_PORTAINER_EDGE_ID	Portainer Edge ID	""
--portainer-edge-key	KUBESOLO_PORTAINER_EDGE_KEY	Portainer Edge Key	""
--portainer-edge-async	KUBESOLO_PORTAINER_EDGE_ASYNC	Enable Portainer Edge Async Mode	false
--local-storage	KUBESOLO_LOCAL_STORAGE	Enable local storage	true
--debug	KUBESOLO_DEBUG	Enable debug logging	false
--pprof-server	KUBESOLO_PPROF_SERVER	Enable pprof server for profiling	false

Example:

To config KubeSolo to use Portainer Edge, you can use the following command:

curl -sfL https://get.kubesolo.io | KUBESOLO_PORTAINER_EDGE_ID=your-portainer-edge-id KUBESOLO_PORTAINER_EDGE_KEY=your-portainer-edge-key sudo -E sh

Documentation

Please see the documentation for complete documentation.

Building from Source

Prerequisites

• Go 1.24 or later
• Docker (for ARM builds and dependency management)
• Cross-compilation toolchains (optional, for cross-platform builds)

Install Cross-Compilation Toolchains

To build for multiple architectures, install the required cross-compilation toolchains:

sudo make install-cross-compilers

This installs:

• gcc-aarch64-linux-gnu (for ARM64)
• gcc-x86-64-linux-gnu (for AMD64)
• gcc-arm-linux-gnueabihf (for ARM/ARMHF)
• riscv64-linux-gnu-gcc(for RISCV64)

Basic Build

Build for your current platform (outputs to ./dist/kubesolo):

make build

Cross-Platform Builds

Build for specific architectures using environment variables:

# Build for ARM64
make build GOARCH=arm64

# Build for AMD64  
make build GOARCH=amd64

# Build for ARM (ARMHF)
make build GOARCH=arm

# Build for RISCV64
make build GOARCH=riscv64

Alpine Linux / musl Builds

For Alpine Linux compatibility, build musl-compatible static binaries:

# Install musl cross-compilers (one-time setup)
sudo make install-musl-cross-compilers

# Build musl binary for specific architecture
make build-musl GOARCH=amd64
make build-musl GOARCH=arm64

# Build all supported musl architectures
make build-all-musl

Note: musl builds are currently supported for amd64 and arm64 architectures only.

Custom Output Path

Specify a custom output path using the OUTPUT variable:

# Custom filename
make build OUTPUT=./kubesolo-custom

# Platform-specific naming
make build GOARCH=arm OUTPUT=./dist/kubesolo-arm

# Different directory
make build OUTPUT=./bin/kubesolo

Combined Examples

# Build ARM binary with custom name
make build GOARCH=arm OUTPUT=./dist/kubesolo-linux-arm

# Build AMD64 binary for CI/CD
make build GOARCH=amd64 OUTPUT=./artifacts/kubesolo-linux-amd64

Development

For development and testing, you can run KubeSolo directly without building:

# Download dependencies first (only needed once)
make deps

# Run KubeSolo in development mode
make dev

Notes

• ARM builds: For ARM architecture, containerd binaries are built using Docker cross-compilation for optimal compatibility
• Dependencies: The build process automatically downloads required dependencies (containerd, runc, CNI plugins) for the target architecture
• CGO: All builds use CGO for better performance and compatibility with system libraries

Community

Getting involved

GitHub Issues - Submit your issues and feature requests via GitHub.

Release cadence

KubeSolo maintains pace with upstream Kubernetes releases but rely on the forked version from k3s. Our goal is to release patch releases within one week, and new minors within 30 days.

Security

Security issues in KubeSolo can be reported by sending an email to [email protected].

TradeMark

KubeSolo and the KubeSolo logo are registered trademarks of Portaner.io Limited