Why K3s

Every cluster Flui creates — observability or workload, on a cloud provider or on a machine you own — runs K3s as its Kubernetes distribution. That choice is load-bearing for the rest of this documentation. This chapter explains why.

The problem K3s solves for Flui

Flui’s core promise is “give me a credential, and in about five minutes I give you a production environment”. To make that promise honest, the Kubernetes layer underneath has to:

1. Boot fast. Provision a VM, run cloud-init, start Kubernetes, reach Ready — under a few minutes.
2. Fit on a small VM. Flui’s smallest viable target is a couple of vCPUs and 4 GB of RAM. A vanilla kubeadm-installed Kubernetes plus etcd plus the standard add-ons does not comfortably fit on that footprint.
3. Carry its own ingress, DNS and default storage out of the box, so the first deployment doesn’t require installing five Helm charts before anything happens.
4. Stay 100% upstream-compatible so that everything Flui leans on (kubectl, Helm charts, standard manifests, cert-manager, the rest of the CNCF ecosystem) just works.

K3s — the lightweight, single-binary Kubernetes distribution maintained by Rancher / SUSE — meets all four. That is why Flui uses it.

How Flui installs K3s

The K3s installation logic is not embedded in the Flui API. It lives in a separate, versioned scripts repository, and the API generates cloud-init that downloads and runs the scripts on each node. The practical benefit: install behaviour is auditable and hot-fixable independently of the Flui API release cycle.

Platform components on every cluster

K3s ships a curated set of add-ons — ingress, cluster DNS, metrics, a default storage class — and Flui uses them as they come. On top, Flui installs a small, deliberate set of its own components: certificate lifecycle, cluster-side authorization, and additional metrics exporters. Everything is reconciled through the same platform-components mechanism, so the inventory on a cluster is predictable and declarative.

Components that run only on the control cluster are described in The control cluster.

OS image and architecture

Today every K3s node Flui creates runs Ubuntu 24.04 LTS, amd64, with cloud-init enabled and SSH ready after first boot. Ubuntu 26.04 LTS — the next long-term release — is being worked on and will become the default once it ships.

Other architectures (ARM in particular) and other Linux distributions are not supported today, but neither is locked out by design. K3s itself runs on more than amd64, and the Flui bootstrap is not tied to a single architecture or distribution. Supporting another one is a matter of verification work, not a redesign.

High availability

Clusters run with a single master today; the datastore is K3s’s default embedded SQLite. Multi-master HA is on the roadmap and will require switching to embedded etcd — a deliberate future change, not a current capability.

What K3s does not do

To make the boundaries explicit, K3s does not handle:

• VM provisioning. That is the cloud provider’s job, via the abstraction described in How Flui works across providers.
• DNS records or external certificates. Those flow through Flui’s own DNS abstraction (DNS integration) and cert-manager (TLS and certificates).
• End-user authentication. Identity flows through Zitadel (Identity and OIDC).
• flui.yaml. Flui translates manifests into standard Kubernetes resources before applying — see The flui.yaml manifest and Catalog vs application.

Creating a cluster shows how these choices combine in practice.