Skip to content
flui.cloud

Multi-cluster topology

A Flui installation is not a single cluster. It is one control cluster and any number of workload clusters operated together as a whole. This chapter is about what that arrangement gives you, where the boundaries lie, and what each cluster knows about the others.

The shape of an installation

Every installation has the same skeleton:

  • One control cluster. Created first, by the CLI bootstrap, and unique within the installation. It hosts the control plane: dashboard, API, identity, database, observability backend.
  • Zero or many workload clusters. Added later, from the dashboard or the CLI. They host user applications and the small set of platform components an application cluster needs.

Every cluster in an installation lives on the same provider as the control cluster. This is what lets workload and control clusters share a private network and reach each other with low latency. Region and node sizing can still vary per cluster — the constraint is the provider, not the geography or the shape of the machines.

If you need to run workloads on a different provider, the answer today is a separate Flui installation on that provider, with its own control cluster and its own workload clusters. The two installations are independent and operate side by side. The CLI is built around this directly: it supports multiple contexts, each one a fully isolated installation with its own credentials, and switching between them is one command — covered in detail in Multi-context.

Why more than one workload cluster

A single workload cluster is the default and a perfectly valid end state. You add more when one of these starts to apply:

  • Environment isolation. A cheap staging cluster, a larger production cluster, kept fully separated.
  • Project or customer separation. One cluster per tenant, so a noisy workload on one tenant cannot starve another.
  • Geographic or regulatory placement. Data that must stay in a region, or workloads that should run close to their users.
  • Blast radius. A cluster that ends up in a bad state takes only its own workloads with it.

Adding a workload cluster is the answer to separation questions, not to scaling questions. Scaling a single application happens on the cluster it already runs on.

What every cluster shares

Regardless of type, every cluster in the installation is a Flui cluster as defined in Cluster as a concept. That means the same identity, the same ownership labels on every provider resource, the same dashboard surfaces (nodes, network, storage, firewall, monitoring), and the same operations available through the same CLI and dashboard.

What only the control cluster carries

The control cluster is the singular host of the control plane. Everything that has to exist exactly once per installation lives on it: the dashboard and API the user talks to, the identity provider that authenticates them, the database that holds the installation’s state, the observability backend that collects metrics and logs from every cluster.

A workload cluster carries only the small set of platform components Flui adds on top of K3s — certificate lifecycle and optional cluster-side authorization — plus the host-level agents that push metrics and logs back to the control cluster.

In other words, the control cluster runs Flui itself, and the workload clusters are where your applications are meant to live. Deploying user applications onto the control cluster is not forbidden — it is a sensible choice for development or staging setups where you want the whole installation on a single server — but it is not the recommended shape for production, where application workloads and the control plane should live on separate clusters.

How the clusters relate

A workload cluster is reachable by the control plane but not by its peers. The relationships are simple:

  • Control plane → workload cluster. The API holds the credentials to reach every workload cluster it created. Deploys, scaling, lifecycle operations and reads all flow this way, over the cluster’s private network whenever possible.
  • Workload cluster → control cluster. Every node pushes metrics and logs to the control cluster’s observability backend over the private network.
  • Workload cluster ↔ workload cluster. Flui does not wire workload clusters to each other. They share no state and have no cross-cluster pod networking. They do sit on the same private network as the rest of the installation, so reachability at the network level exists, but Flui does not surface or manage a path between them — cross-cluster app-to-app communication is not a feature Flui exposes today.

Failure boundaries

The arrangement above translates directly into failure handling:

  • A workload cluster failing affects only the workloads on that cluster. The control plane keeps running, the other workload clusters keep serving traffic, and you can drive the recovery from the dashboard.
  • The control cluster failing takes the control plane offline — no dashboard, no API, no central log and metric queries — but every workload cluster keeps operating normally. Each cluster is autonomous in steady state; the control plane is the way you change the installation, not the way you keep it running.

This is the practical meaning of blast radius: nothing about an installation makes the failure of one cluster cascade into another.

Working with more than one cluster

The dashboard and the CLI list every cluster of the installation together. When an operation targets a specific one you pick which; with a single workload cluster the pick is implicit.

The only exception is destroying the control cluster, which stays CLI-only — see Creating a cluster from zero.

Where this chapter goes from here