Configuration

The configuration file

KubeSolo reads its settings from one YAML file, /etc/kubesolo/config.yaml. The installer creates it, and the service starts KubeSolo with --config=/etc/kubesolo/config.yaml. A file only needs the keys it changes; anything omitted keeps its default.

The file lives outside the data directory on purpose: it holds settings, not cluster state, so it survives kubesoloctl reset. It is written 0600 and owned by root because it can hold portainer.edgeKey, a credential. A file that declares an apiVersion KubeSolo does not recognise is rejected.

When changes take effect

On restart. KubeSolo reads its configuration once at startup and derives every path, certificate and component argument from it. There is no live reload.

One setting can never change: path. Every certificate, the cluster database and all container state live below it, and nothing moves them. Choose it at install time.

Precedence

Four layers, lowest to highest. Each layer overrides only the settings it actually sets.

If a change in the file seems to have no effect, a flag or environment variable in the service definition is overriding it:

To see what KubeSolo actually resolves, without starting anything:

Editing the configuration

With kubesoloctl

Nothing is written until validation passes, so a rejected value leaves the file as it was. List and map settings take the same form as their flag: kubernetes.apiServer.extraSANs takes 10.0.0.4,kubesolo.local, and kubernetes.kubelet.systemReserved takes cpu=1,memory=500Mi.

By hand

The file is plain YAML. When KubeSolo or kubesoloctl writes it, comments are dropped and keys are sorted alphabetically; the previous version is kept as /etc/kubesolo/config.yaml.bak. Validate hand edits before restarting with sudo kubesoloctl config validate.

The repository ships an annotated example file with every setting at its default and a command to verify each one.

The whole document

Every setting at its default:

Every setting

Every setting, with its deprecated flag and its environment variable. All of them except path apply on the next restart.

A few combinations are rejected at startup: d2k.enabled without network.loadBalancer.enabled, and the static CPU manager policy in container mode. On arm and riscv64, d2k disables itself with a warning. An MTU below 1280 warns that IPv6 pod traffic may not fragment correctly.

Flags: deprecated, still honoured

Every KubeSolo flag in the table above still works and still overrides the file, so existing installs keep running. They are deprecated: no new flags will be added, and new settings are available only through the file. Boolean flags also have a negated form, such as --no-load-balancer.

Migrating a flag-based install

Installs made before v1.2.1 pass settings as flags in the service definition. kubesoloctl upgrade converts them automatically and keeps the old service file as .bak. To do it by hand, run the binary with the flags the service currently passes plus --print-config, then save the result:

Then reduce the service command line to one flag and restart:

Configuration API

KubeSolo can serve its configuration over a unix socket, so it can be read and changed programmatically. It is off by default:

The socket is mode 0600 and owned by root. File permissions are the whole access model: there is no token and no TLS, because there is no network listener. Anything that can open the socket can change the configuration. Changes made through the API are desired state; they take effect on the next restart, and every write response lists the settings that need one.

Reads return an ETag; send it back as If-Match to get a 412 if the configuration changed underneath you. Changing path returns 409, and an invalid configuration returns 422. A rejected request writes nothing. Each write is logged with the setting paths it changed, never their values: journalctl -u kubesolo | grep configapi.

The full reference is in the repository: docs/configuration/config-api.md.