Install KubeSolo: Single-node Kubernetes in under 60 seconds

Step 1: Prepare your system

Install a modern Linux distribution on your device. Ensure the following prerequisites are in place before running the installer. On macOS or Windows, skip to kubesoloctl.

Architecture

x86_64 · ARM64 · ARMv7 · RISC-V 64

glibc or musl

RAM

200 MB+ free

Permissions

root or sudo

Dependencies

curl · iptables

iptables with xt_comment; plus nftables on Alpine

Kernel

cgroups enabled

cpuset · cpu · io · memory · pids

Hostname

Lowercase RFC 1123

a-z, 0-9, - and .

Init system

Any

systemd, OpenRC, SysV, s6, runit, upstart, or none

Storage

Sufficient local disk

For workload data

kubectl

Optional

Local or on a remote machine

Important: the installer stops if Docker is installed or running, because Docker's own containerd and network rules interfere with KubeSolo. Remove Docker first, or use kubesoloctl container mode on a development machine. Other engines are not checked, but a running Podman or host containerd can still conflict with KubeSolo networking. To run KubeSolo on top of a host containerd or CRI-O on purpose, see attaching a host runtime.

kubectl on low-RAM devices: Avoid running kubectl on machines with less than 512 MB of RAM, as it may impact performance. Use kubectl from an external machine instead.

Step 2: Install KubeSolo

Run the install script. It detects your architecture, libc and init system, installs the KubeSolo binary, writes /etc/kubesolo/config.yaml, and starts KubeSolo as a service.

bash
1$ curl -sfL https://get.kubesolo.io | sudo sh -

To follow progress on systemd hosts, check the service logs. On other init systems, the installer prints where the logs are.

bash
1$ journalctl -u kubesolo -f

The admin kubeconfig is written to /var/lib/kubesolo/pki/admin/admin.kubeconfig.

Online, offline and air-gapped

The default online build pulls some system images when it first starts. For sites without reliable internet, install the offline build, which embeds them:

bash
1$ curl -sfL https://get.kubesolo.io | sudo sh -s -- --offline

For a machine with no internet at all, prepare a bundle on a connected machine and install from it. See air-gapped installation.

Installer flags and versions

Pass options after sh -s --. Pin the version in automation so every device gets the same build:

bash
1$ curl -sfL https://get.kubesolo.io | sudo sh -s -- \
2  --version=v1.2.1 \
3  --apiserver-extra-sans=kubesolo.local \
4  --local-storage=true

The installer records your options in /etc/kubesolo/config.yaml, and KubeSolo reads that file every time it starts. Every option is listed in installer flags.

Portainer integration (optional)

To install KubeSolo and connect it to a Portainer server in one step, pass your Edge credentials as environment variables:

bash
1$ curl -sfL https://get.kubesolo.io | KUBESOLO_PORTAINER_EDGE_ID=${YOUR_EDGE_ID} KUBESOLO_PORTAINER_EDGE_KEY=${YOUR_EDGE_KEY} sudo -E sh

Alternative: kubesoloctl (Linux, macOS, Windows WSL2)

kubesoloctl is a single CLI for install, upgrade, reset and uninstall. On Linux it installs KubeSolo as a service. On macOS and Windows (WSL2), its container mode runs KubeSolo in a Docker container for development and CI. Download it from the releases page (kubesoloctl-<os>-<arch>), then:

bash
1# Linux host, as a system service
2$ sudo kubesoloctl install
 
4# macOS, WSL2 or a Linux dev box with Docker
5$ kubesoloctl install --run-mode=container --container-ports=8080:80

Both merge the admin kubeconfig into ~/.kube/config for you.

Step 3: Confirm it's working

On the node

If kubectl was installed on the node before you ran the installer, the installer already merged the admin kubeconfig into ~/.kube/config for your user. Otherwise, point kubectl at it directly:

bash
1$ sudo kubectl --kubeconfig /var/lib/kubesolo/pki/admin/admin.kubeconfig get nodes

From another machine

Copy /var/lib/kubesolo/pki/admin/admin.kubeconfig to the machine where kubectl is installed. It is readable by root only, so copy it with sudo. Then use it for the current shell without touching your existing configuration:

bash
1$ export KUBECONFIG=$PWD/admin.kubeconfig

Or merge it permanently into your existing kubeconfig:

bash
1# merge and back up existing config
2$ KUBECONFIG=~/.kube/config:./admin.kubeconfig kubectl config view --merge --flatten > /tmp/kubeconfig.merged
3$ cp ~/.kube/config ~/.kube/config.bak
4$ mv /tmp/kubeconfig.merged ~/.kube/config
 
6# switch to the KubeSolo context
7$ kubectl config use-context kubernetes-admin@kubesolo

The kubeconfig points at https://<node IP>:6443. If the node has several network interfaces, pin the address KubeSolo uses with network.nodeIP. If you reach the node through a hostname, NAT or another address, add it with --apiserver-extra-sans at install time, or kubernetes.apiServer.extraSANs later, and edit the server: line to match. See node IP.

Verify node status

bash
1$ kubectl get nodes
2# You should see a single node in Ready state

Step 4: Deploy your first workload

Start with the Mosquitto example from the KubeSolo repository:

bash
1$ kubectl apply -f https://raw.githubusercontent.com/portainer/kubesolo/develop/examples/mosquitto.yaml
 
3# check resources in the mosquitto namespace
4$ kubectl get all -n mosquitto
5$ kubectl get svc -n mosquitto

The example exposes MQTT on port 1883 through a NodePort Service. Reach it on the node's IP and the NodePort shown by kubectl get svc. To expose a service on its own port, use a LoadBalancer Service.

Step 5: Change settings later

You do not need to reinstall to change a setting. Edit /etc/kubesolo/config.yaml, or use kubesoloctl, then restart KubeSolo:

bash
1$ sudo kubesoloctl config set metrics.enabled true
2$ sudo systemctl restart kubesolo

Every setting is listed in the configuration reference.

Uninstall

The uninstall script removes KubeSolo, its service and its configuration file, and keeps the data directory:

bash
1$ curl -sfL https://uninstall.kubesolo.io | sudo sh -

With kubesoloctl, which also removes container-mode instances:

bash
1$ sudo kubesoloctl uninstall           # keep cluster data
2$ sudo kubesoloctl uninstall --purge   # also delete /var/lib/kubesolo

For options such as --remove-data and --remove-kubeconfig, run the script locally. See uninstalling.

Get started with KubeSolo

Step 1: Prepare your system

Step 2: Install KubeSolo

Online, offline and air-gapped

Installer flags and versions

Portainer integration (optional)

Alternative: kubesoloctl (Linux, macOS, Windows WSL2)

Step 3: Confirm it's working

On the node

From another machine

Verify node status

Step 4: Deploy your first workload

Step 5: Change settings later

Uninstall

Next steps

Full documentation

Configuration reference

Portainer fleet management