Why K3s

Every cluster Flui creates, control or workload, on a cloud provider or on a machine you own, runs K3s as its Kubernetes distribution. The rest of this documentation depends on that choice, and this chapter explains it.

The problem K3s solves for Flui

Flui turns a supported provider key, or a server of your own, into a complete platform in about five minutes. For that to work, the Kubernetes layer underneath has to:

1. Boot fast. Provision a VM, run cloud-init, start Kubernetes and reach Ready, all inside those five minutes.
2. Fit on a small VM. The largest machine an installation needs is the control cluster’s: the API, its database, identity and the observability backend all share it, and the minimum there is 2 vCPUs, 4 GB of RAM and 40 GB of disk. flui env create warns before buying anything smaller. A workload cluster carries much less (ingress, certificates, the agents that ship its logs and metrics) and starts on about 2 GB. A node that only adds capacity carries less again, so its size is set by the applications you put on it.
3. Carry its own ingress, DNS and default storage out of the box, so the first deployment does not require installing five Helm charts first.
4. Stay 100% upstream-compatible, so that everything Flui relies on (kubectl, Helm charts, standard manifests, cert-manager, the rest of the CNCF ecosystem) works.

K3s, the lightweight single-binary Kubernetes distribution maintained by Rancher/SUSE, meets all four.

How Flui installs K3s

The K3s installation logic lives in a separate, versioned scripts repository, not in the Flui API. The API generates cloud-init that downloads and runs the scripts on each node, so install behaviour can be audited and hot-fixed independently of the Flui API release cycle.

Platform components on every cluster

K3s ships a 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 set of its own components: certificate lifecycle, cluster-side authorization and additional metrics exporters. Everything is reconciled through the same platform-components mechanism, so what runs 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

Every node Flui creates on a cloud provider runs Ubuntu 24.04 LTS, with cloud-init enabled and SSH ready after first boot. Ubuntu 26.04 LTS shipped in April 2026; the default has not moved to it yet.

The architecture a node can have depends on how it joins the cluster.

A node Flui provisions for you is x86_64. You do not choose an architecture when you create a cluster on a provider (there is no flag for it), and where a provider sells ARM machine sizes, they are filtered out of the list you pick from.

A machine you bring may be ARM. Installing onto a server you already own (creating a cluster on it, or attaching it to an existing cluster as a node) starts with a probe of the host: its distribution, architecture, memory, CPUs, and whether K3s is already there. Three findings stop the install: an architecture other than x86_64, aarch64 or arm64; less than about 2 GB of memory; K3s already installed. --best-effort continues past them and --skip-precheck skips the probe, but neither changes the machine: an unsupported architecture is refused again by the installer itself.

Passing that check does not mean everything downstream is ready for ARM. One place still assumes x86_64: when Flui lists the tags available for a container image, it shows only the tags that have a linux/amd64 build.

Other Linux distributions are not supported yet. The installer accepts Ubuntu 22.04 and 24.04 and stops on anything else. Ubuntu 26.04 is the next one to support; any other distribution is verification work that has not been done yet.

High availability

Clusters run with a single master. The datastore is K3s’s embedded etcd, switched on from the first boot, so a cluster does not have to change datastore to gain more masters later. Flui does not add more masters (multi-master HA) yet.

The applications Flui runs can still be highly available; High availability explains how, and what that covers.

What K3s does not do

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 them. See The flui.yaml manifest and Catalog vs application.

Creating a cluster shows how these choices combine in practice.