Step 1: Prepare your system
Install a modern Linux distribution on your device. Ensure the following prerequisites are in place before running the installer.
Architecture
x86_64 · ARM · ARM64 · RISC-V 64
Dependencies
curl · iptables
libsqlite3-dev also required
Storage
Sufficient local disk
For workload data
kubectl
Optional
Local or on a remote machine
Important: Ensure no container engine (Docker, Podman, containerd) is installed or active on the target system before proceeding. This includes background services or residual installations that could interfere with KubeSolo networking.
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. This installs the KubeSolo binary and starts the control plane as a systemd service.
BASH
1$ curl -sfL https://get.kubesolo.io | sudo sh -
To view installation progress, check the systemd service logs:
BASH
1# on Debian-based systems
2$ journalctl -u kubesolo -f
The admin kubeconfig is written to /var/lib/kubesolo/pki/admin/admin.kubeconfig.
Portainer integration (optional)
To install KubeSolo and connect it directly 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
Uninstall
BASH
1$ curl -sfL https://uninstall.kubesolo.io | sudo sh -
Step 3: Confirm it's working
Set up kubectl access
Copy the admin kubeconfig from the KubeSolo node to the machine where kubectl is installed, then use one of the following methods to connect.
Temporarily use the kubeconfig without overwriting your existing one:
BASH
1KUBECONFIG=./admin.kubeconfig
Or permanently merge it into your existing kubeconfig:
BASH
1# merge and back up existing config
2KUBECONFIG=~/.kube/config:./admin.kubeconfig kubectl config view --merge --flatten > /tmp/kubeconfig.merged
3cp ~/.kube/config ~/.kube/config.bak
4mv /tmp/kubeconfig.merged ~/.kube/config
6# switch to the KubeSolo context
7kubectl config use-context kubernetes-admin@kubesolo
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
Access the app via the node's static IP and NodePort, or via ingress depending on your setup.