Installation

Ways to install

KubeSolo is a single Linux binary. There are three ways to put it on a machine:

Supported architectures are x86_64 (amd64), aarch64 (arm64), armv7l (arm) and riscv64. Every architecture is published for both glibc and musl, as an online and an offline build. Check the host first with the requirements in the quick start.

Install channels

Two URLs serve the install script. Flags work the same way on both.

Running the install script

The script must run as root. Pipe it to sh through sudo:

To pass flags through a pipe, use sh -s --. -s makes the shell read the script from stdin, and everything after -- goes to the script instead of to sh:

Every option also has an environment variable. sudo drops the caller's environment, so use sudo -E when you set them in front of the command:

With a downloaded copy of the script, pass flags as usual: sudo sh install.sh --version=v1.2.1.

What the script does

1. Detects the architecture, glibc or musl, the init system and whether it is running in a container.
2. Runs pre-flight checks. It stops if Docker is installed or running, if the hostname is not lowercase RFC 1123, if iptables or its xt_comment module is missing, if the cpuset, cpu, io, memory or pids cgroup controllers are missing, or (on Alpine) if nft is missing.
3. Stops any running KubeSolo and frees its ports (2379, 6443, 10443, 6060), killing only processes whose executable is /usr/local/bin/kubesolo.
4. Downloads kubesolo-<version>-linux-<arch>[-musl][-offline].tar.gz from GitHub releases and installs the binary to /usr/local/bin/kubesolo.
5. Writes your settings to /etc/kubesolo/config.yaml (mode 0600). The installed binary produces the file itself with --print-config, so the service command line is just kubesolo --config=/etc/kubesolo/config.yaml.
6. Creates and starts a service for the detected init system.
7. If kubectl is on the node, waits for the admin kubeconfig and merges it into ~/.kube/config for the user who ran sudo, backing up the existing file first.

Online and offline builds

Every release ships two variants of the binary:

To install the offline build on a connected machine, add --offline (or set KUBESOLO_OFFLINE=true):

Your own workload images still come from a registry. For air-gapped workloads, point containerd at an internal registry. See registry mirrors.

Pinning a version

The script installs the release it was published with unless you pass --version. Pin the version in automation so every device gets the same build:

Versions are release tags such as v1.2.1, as listed on the releases page. Running the script again with a newer --version upgrades in place. See Upgrading.

Installer flags

The script accepts these options. Boolean options take an explicit value (--debug=true), except --offline and --install-prereqs, which take none.

This works because the installer generates /etc/kubesolo/config.yaml by running the installed binary with --print-config, and the binary reads every recognised KUBESOLO_* variable. The variable names are listed in the settings table.

Changing settings after install

From v1.2.1 the installer records every setting in /etc/kubesolo/config.yaml, and the service reads that file at startup. To change a setting later, edit the file instead of reinstalling, then restart KubeSolo:

Running the script again starts from the existing file and applies only the flags you pass, so settings you changed in the file survive a re-run. The configuration reference lists every setting, its flag and its environment variable.

Air-gapped installation

An air-gapped node needs the offline build, because the online build pulls system images at startup.

With the install script

On a connected Linux machine with the same architecture and libc as the target, download the offline archive and a copy of the script. --download-only needs no root and runs no pre-flight checks, so the machine can have Docker installed:

Copy the directory to the target, then install from the archive:

Pass the archive the download saved. Its name follows the detected platform: kubesolo-<version>-linux-<arch>[-musl]-offline.tar.gz, for example kubesolo-v1.2.1-linux-amd64-offline.tar.gz. The bundle is built for the OS, architecture and libc of the downloading machine, so a bundle fetched on macOS or on a glibc host for an Alpine target won't work. If the target has a different architecture or libc than the machine you download on, fetch the matching archive directly from the release instead, for example:

With kubesoloctl

kubesoloctl download builds a bundle for another architecture with --arch (amd64, arm64, arm, riscv64, each with an optional -musl suffix):

Workload images are separate from the system images. Mirror them to an internal registry and use a catch-all _default mirror so that every pull goes there.

Init systems and run modes

With the default --run-mode=service, the script detects the init system in this order and writes the matching service definition:

Two other run modes skip the init system entirely:

• --run-mode=daemon starts KubeSolo in the background with nohup, writing its PID to /var/run/kubesolo.pid and logs to /var/log/kubesolo.log.
• --run-mode=foreground runs KubeSolo in the current terminal, for debugging.

For an image you build yourself, such as Yocto or Buildroot, install the binary from the release archive and start it from your own init script with /usr/local/bin/kubesolo --config=/etc/kubesolo/config.yaml.

Alpine Linux and musl

The script detects musl from /lib/ld-musl-*.so.1 and downloads the static -musl build, so Alpine and other musl distributions need no extra libraries. Alpine needs three things that other distributions usually already have:

• iptables, for the installer's pre-flight check;
• nftables, because kube-proxy runs in nftables mode on Alpine;
• the OpenRC cgroups service, so the cgroup v2 controllers are available.

Run it as root, since Alpine does not ship sudo by default. --install-prereqs installs nftables if it is missing and runs rc-update add cgroups boot and rc-service cgroups start. KubeSolo itself is registered as an OpenRC service.

Behind a proxy

--proxy writes HTTP_PROXY and HTTPS_PROXY into the service environment for every init system and run mode, and sets NO_PROXY=localhost,127.0.0.1. The installer's own downloads follow your shell's proxy settings as usual.

Upgrading

Run the installer again with the new version. It stops KubeSolo, replaces the binary and restarts the service. The data directory and /etc/kubesolo/config.yaml are kept.

Or use kubesoloctl, which also moves a flag-based service definition from an older release into the configuration file:

Uninstalling

The hosted uninstall script stops KubeSolo, removes the service definition, binary, CNI configuration and /etc/kubesolo/config.yaml, and leaves the data directory in place:

For the options, download the script from the release and run it locally. --remove-data asks for confirmation, so it needs a terminal rather than a pipe:

With kubesoloctl, which works for both host installs and container mode: