What kubesoloctl is
kubesoloctl is a single, dependency-free binary that manages the whole KubeSolo lifecycle: pre-flight checks, download, service setup, kubeconfig wiring, configuration, upgrades, reset and uninstall. It runs KubeSolo in one of two ways:
- On the host (Linux): installs the KubeSolo binary and runs it as a system service. This is the production path for edge devices and gateways.
- In a container: runs KubeSolo inside a container on Docker. This is for development and CI on macOS, Windows (WSL2) or any Linux machine with Docker. On macOS it is the only mode, because KubeSolo is Linux-only.
It complements the install script, which remains the quickest way to install on a Linux host.
Getting kubesoloctl
Download the binary for your platform from the release and put it on your PATH:
Assets are named kubesoloctl-<os>-<arch>. Published targets: linux-amd64, linux-arm64, linux-arm (ARMv7; ARMv6 boards such as the Pi 1 and original Pi Zero are not supported), linux-riscv64, darwin-amd64 and darwin-arm64. On Windows, use the Linux binary inside WSL2. kubesoloctl is a pure-Go binary, so the same file works on glibc and musl.
Run modes
| Mode | Flag | Where KubeSolo runs | Typical use |
|---|---|---|---|
| service | (default on Linux) | Binary under the host init system | Production, edge |
| container | --run-mode=container | Inside a Docker container | Development and CI on macOS, WSL2 or Linux |
| daemon | --run-mode=daemon | Background process with a PID file | Hosts without a supported init system |
| foreground | --run-mode=foreground | The current terminal | Debugging |
On macOS the mode is always container; asking for another mode is an error.
Installing on a Linux host
install runs the pre-flight checks (root, RFC 1123 hostname, no Docker, iptables xt_comment, nftables and iptables on Alpine, cgroup controllers, free ports 2379, 6443 and 10443), installs /usr/local/bin/kubesolo, writes /etc/kubesolo/config.yaml, starts the service and merges the admin kubeconfig into ~/.kube/config.
install flags
| Flag | Env var | Default | Description |
|---|---|---|---|
| --version | KUBESOLO_VERSION | v1.2.1 | KubeSolo release to install (defaults to the version kubesoloctl was built for). |
| --path | KUBESOLO_PATH | /var/lib/kubesolo | Data directory. |
| --run-mode | KUBESOLO_RUN_MODE | service | service, daemon, foreground or container. |
| --name | KUBESOLO_NAME | kubesolo | Instance name: container name and kubeconfig context in container mode. |
| --node-ip | KUBESOLO_NODE_IP | auto-detect | Pin the node IP on multi-NIC hosts. |
| --mtu | KUBESOLO_MTU | auto-detect | MTU for the CNI bridge. In container mode it also sizes the Docker network the container runs on. |
| --apiserver-extra-sans | KUBESOLO_APISERVER_EXTRA_SANS | (none) | Extra SANs for the API server certificate. |
| --d2k | KUBESOLO_D2K | false | Docker-compatible API translator on port 2376. |
| --d2k-namespace | KUBESOLO_D2K_NAMESPACE | d2k | Namespace d2k uses. |
| --portainer-edge-id | KUBESOLO_PORTAINER_EDGE_ID | (none) | Portainer Edge ID. |
| --portainer-edge-key | KUBESOLO_PORTAINER_EDGE_KEY | (none) | Portainer Edge key. |
| --portainer-edge-async | KUBESOLO_PORTAINER_EDGE_ASYNC | false | Edge async mode. |
| --portainer-edge-image | KUBESOLO_PORTAINER_EDGE_IMAGE | docker.io/portainer/agent:lts | Edge Agent image. |
| --cpu-manager-policy | KUBESOLO_CPU_MANAGER_POLICY | none | static gives Guaranteed pods exclusive cores. Not in container mode. |
| --cpu-manager-policy-options | KUBESOLO_CPU_MANAGER_POLICY_OPTIONS | (none) | Options for the static policy. |
| --reserved-cpus | KUBESOLO_RESERVED_CPUS | 0 under static | Cpuset reserved for the host. |
| --system-reserved | KUBESOLO_SYSTEM_RESERVED | (none) | Resources withheld from allocatable. |
| --debug | KUBESOLO_DEBUG | false | Debug logging. |
| --pprof-server | KUBESOLO_PPROF_SERVER | false | pprof server on port 6060. |
| --proxy | KUBESOLO_PROXY | (none) | HTTP/HTTPS proxy injected into the service environment. |
| --offline-install | KUBESOLO_OFFLINE_INSTALL | (none) | Install from a local .tar.gz or binary. |
| --install-prereqs | KUBESOLO_INSTALL_PREREQS | false | Install missing OS prerequisites, such as nftables on Alpine. |
| --image | KUBESOLO_IMAGE | portainer/kubesolo:<version> | Container image for container mode. |
| --container-ports | KUBESOLO_CONTAINER_PORTS | (none) | Host ports to publish in container mode. Ignored, with a warning, on host installs. |
CPU pinning options are validated before anything is installed, so a bad cpuset fails immediately instead of crash-looping the service.
Local storage is on by default. To turn it off, set storage.localPath.enabled: false in /etc/kubesolo/config.yaml and restart. That only stops KubeSolo deploying it on later starts. If it is already running, also remove it with kubectl delete namespace local-path-storage and kubectl delete storageclass local-path. Settings without an install flag, such as the metrics endpoint, are changed the same way with kubesoloctl config set.
Container mode (macOS, WSL2, Linux dev)
Container mode needs a reachable Docker engine (Docker Engine or Docker Desktop). kubesoloctl honours DOCKER_HOST.
kubesoloctl starts the portainer/kubesolo:<version> image, publishes the API server on a random localhost port, and merges a kubeconfig that points at it. Inside the container, KubeSolo switches to container mode, which adjusts cgroups, mounts, DNS and eviction thresholds so the node starts cleanly in a container.
The host port can change after an upgrade or reset. Refresh the kubeconfig when it does:
Publishing workload ports
In container mode KubeSolo has its own network namespace, so NodePort and LoadBalancer services and hostPort pods are reachable only on ports published when the container is created. This is the same model as Kind's extraPortMappings:
| Entry | Meaning |
|---|---|
| 9001 | Host 9001 to container 9001. |
| 9000-9100 | A range, host port equal to container port. |
| 8080:80 | Host 8080 to container 80. |
| 127.0.0.1:80:80 | Bind on one host IP only. |
| 53/udp | UDP. TCP is assumed otherwise. |
Bare ports and ranges bind on all interfaces, so other machines can reach them. Scope a port to localhost with the 127.0.0.1:host:container form. Published ports are kept across upgrade and reset.
Running several instances
--name runs independent instances side by side in container mode. Each gets its own container (kubesolo-<name>), data volume and kubeconfig context, plus its own Docker context with d2k. Pass the same --name to upgrade, reset, uninstall and d2k fetch. For kubeconfig fetch, set KUBESOLO_NAME or pass --container=kubesolo-<name>:
Command reference
| Command | Purpose |
|---|---|
| install | Install KubeSolo and start the service or container. |
| check | Run the pre-flight checks only. Flags: --install-prereqs, --pprof-server (also check port 6060). |
| upgrade --version=<v> | Upgrade to a newer release, keeping data and configuration. |
| reset | Wipe all cluster state and start a fresh cluster, keeping the install. |
| uninstall | Stop and remove KubeSolo and its service files; optionally its data. |
| kubeconfig | Print, write, view or merge the admin kubeconfig. |
| config | Read, change, edit and validate /etc/kubesolo/config.yaml. |
| d2k fetch | Create a Docker context for the d2k endpoint of a container-mode instance. |
| download | Build an offline bundle for an air-gapped machine. |
| completion | Generate shell completion for bash, zsh, fish or PowerShell. |
| version | Print kubesoloctl version information. |
Each command detects whether the instance runs as a container or a host service and acts on it.
upgrade, reset and uninstall
| Command | Flags |
|---|---|
| upgrade | --version (required), --offline-install, --name. On a host install it stops the service, replaces the binary, moves a flag-based service definition into the configuration file, and restarts. |
| reset | --force, --path, --name. Deletes the database, certificates and CNI configuration, keeps the binary and service, and restarts into a fresh cluster. |
| uninstall | --purge (also delete /var/lib/kubesolo), --remove-kubeconfig, --keep-config (keep /etc/kubesolo/config.yaml, which is removed by default), --name. |
kubeconfig
fetch reads from the container when one is running and from the local data directory otherwise. fetch and view accept --container, --socket (Docker socket) and --path.
config
Nothing is written until validation passes. When the configuration API is enabled, config goes through it instead of editing the file under the running process. Changes take effect on the next restart; kubesoloctl prints which settings need one. The --config flag points at a file other than /etc/kubesolo/config.yaml.
d2k fetch
For a container-mode instance installed with --d2k, d2k fetch copies the CA and client certificate out of the container into ~/.docker/d2k/<name>/ and creates a Docker context named after the instance:
The published d2k port is random, so run d2k fetch again after each upgrade or reset. For a host install, see connecting to d2k.
download
The bundle holds the KubeSolo release archive and the kubesoloctl binary. On macOS --arch is required, since there is no macOS KubeSolo binary. See air-gapped installation.