Creating a cluster

You run a single command. A few minutes later you have a working cluster with a dashboard open in your browser, an API answering on a real URL, an identity provider managing the login, a database, a metrics and log stack, ingress and certificates, all wired together and reachable. There is no second step where you install the platform on top of the cluster: the command installs the platform.

This chapter covers the choices that decide what that command produces: where the cluster lives, how it is addressed, what kind of certificate it presents on day one, what storage it carries and who can reach it.

The chapter is written around the control cluster, the first cluster of any Flui installation and the one that hosts the control plane. The same applies to a workload cluster, minus the control-plane parts.

The commands, in order, are in the task pages. This chapter explains what you are choosing and which surface can make each choice.

The choices that shape a cluster

Every cluster is described by a handful of inputs. Most have sensible defaults; the ones you change usually match a concrete constraint (a region close to your users, a server shape that fits your workload, a stricter firewall).

Choice	What it controls
Provider	Which cloud the cluster runs on, or your own machine (see below).
Region	Which provider region the servers sit in. Defaults to the provider’s default region.
Server type	The shape (CPU / RAM / disk) of every node. Defaults to the recommended size for the chosen provider.
Firewall	Whether Flui installs and locks down a default firewall and, where the provider has a firewall of its own, which source IPs may reach the master over SSH.
Certificate mode	Whether the cluster issues a real Let’s Encrypt certificate or a staging one (see below).
Shared storage	Whether the cluster includes a master-hosted shared volume (the default) or falls back to per-node local storage.

A cluster is created master-only by default. On a provider Flui can buy from, it already has a scaling group at that point, set to hold the nodes it has: adding a worker means raising the group’s floor, and letting the cluster buy machines for itself means telling the group it may act on its own. On your own servers a node joins when you attach it (covered in Nodes and cluster topology). Growing the root disk on a server type that allows it is a separate operation you run later.

Which surface can create one

Once the control cluster is up, the CLI and the dashboard cover most of the same ground, but not all of it. Each gap has a mechanical reason.

The control cluster is created from the CLI or from the web. There is no dashboard to create it from: the dashboard is one of the things the install brings, together with the API and the identity provider. flui env create does it from your machine. The same install can start from app.flui.cloud instead: you pick one of the supported providers, and either the page runs the install with your provider token, or it hands you the flui env create command to run yourself, so the token never leaves your machine. Either way the cluster lands on your own provider account, the page keeps no access to it, and you take it over with flui env adopt.

Workload clusters are created from the dashboard or the CLI. The dashboard carries a creation wizard that walks through name, provider and region; server type; SSH keys; the private network and its subnet; how the cluster will be addressed; the firewall; and a review before anything is bought. It then shows you a progress screen while the cluster builds.

From the CLI, flui cluster create does the same in one command. It starts from the control cluster’s provider and region and joins its private network on its own; --provider places the cluster elsewhere, including on servers of your own. The same surface lists and destroys clusters (flui cluster list, flui cluster destroy), changes their nodes through the scaling group (flui scaling floor), and attaches or detaches a machine of your own (flui node connect, flui node remove).

An agent can create a cluster too, and when it tries, the call stops and asks a person first. That permission is only ever given once: a request to create something that does not exist yet has no resource to name, so there is nothing narrow enough to record as a standing permission. See The action cycle.

Some things only the CLI can do, because they touch your own machine or reach the provider directly, with no control plane in the middle:

• flui vault init | unlock | lock | status: the credentials this CLI stores on your machine are protected by a passphrase. A browser cannot lock a file on your laptop. See The vault.
• flui env adopt: take over an installation you did not provision yourself. It rebuilds the local profile on your machine and opens SSH to the nodes on your own key. See Taking over an installation.
• flui env scrub: when a provisioning run dies half-way, it leaves servers, firewalls and keys billing to your provider account with no cluster to show for them. scrub reads the resource list that run reported and clears what is left, talking to the provider with the credentials in this machine’s profile. Nothing is deleted unless you pass --delete. See When a run dies half-way.
• Destroying the control cluster (flui env destroy), for the same mechanical reason as creating it: the dashboard and the API are running on the cluster being deleted. See flui env destroy.

One thing only the dashboard and the API can do: answer an agent’s paused write. When an agent asks to create a cluster, add nodes, or spend money, the call does not run. It becomes a question, answered on the dashboard’s Agents page or over the API directly. There is no flui command for it. If the terminal is your only surface, the pause still applies and you answer somewhere else. See When your agent stops to ask you.

A machine you already own

Not every cluster has to be bought. If you already have a server (a rented box, a machine in an office, hardware in a rack), you can use it instead of provisioning another one.

flui env create --host <address> installs onto that machine over SSH instead of provisioning anything at a provider. Flui reuses an SSH key that already works on the host; if none does, it authorises one, asking for the host password once and never storing it. A readiness check runs first, so you find out the machine is unsuitable before anything is written to it.

Only the CLI has this path; the dashboard’s wizard only buys machines. The steps, the precheck and the firewall on your own machine are in Install onto a machine you already own.

Addressing: nip.io by default, your domain when you want one

A new cluster needs a stable URL as soon as it is up, for the dashboard, the API and the identity provider. Buying a domain and pointing it at the cluster takes longer than creating the cluster, so Flui makes this work without a domain.

By default the cluster is addressed through nip.io: the master’s public IP is encoded in the hostname (something like api.warm-finch-zs.203-0-113-10.nip.io), and any name built that way resolves to the master. You create no DNS record, wait for no propagation and configure no registrar. The cluster is reachable as soon as it is up.

When you want the cluster behind a domain you own, Flui handles the switch: DNS records, certificates and the control-plane endpoints are rewired in place, without re-creating the cluster. See DNS integration.

TLS from minute zero

Every Flui cluster starts with a TLS certificate, and there is no separate step to set up certificate issuance. When the cluster comes up, the certificates the control plane needs are already issued, and the dashboard is on HTTPS the first time you open it.

At creation time you choose which Let’s Encrypt endpoint issues the certificate:

• Production (default). A real, browser-trusted certificate. The cluster is immediately usable from any client without TLS warnings.
• Staging. A Let’s Encrypt staging certificate, which browsers do not trust but which does not count against ACME’s production rate limits. Useful when you expect to create and destroy the cluster several times in a short window, for example while developing against Flui itself.

Let’s Encrypt enforces several production rate limits on rolling weekly windows that do not reset on demand. The one most easily hit is the limit on duplicate certificates for the same set of identifiers. To stay clear of it, Flui draws a random prefix for every cluster from a pool of roughly six hundred thousand combinations (something like warm-finch-zs.…), so two clusters asking for exactly the same names is unlikely, though not impossible. The other limits (per registered domain in particular) still apply, and they matter if you re-create clusters repeatedly: a few times a week is fine, a tight test loop is not.

Staging removes those limits, at the cost of an untrusted certificate your CLI and browser will warn about until you allow it. If you create and destroy clusters often (automation, integration tests, demo environments), use staging.

A cluster started in staging can later be moved to production. Moving from production to staging is rarely useful and is not supported.

Storage: shared by default, local on request

When the provider supports attachable block storage, a new cluster comes with a shared storage volume attached to the master and exposed to every worker over the private network. A local cache on each node means repeated reads do not pay the network cost every time. Any workload that keeps persistent state uses this volume by default. On providers without attachable block storage there is no shared volume, and workloads use per-node local storage.

About the default volume:

1. It is one provider-attached volume, sized at creation. It can be grown later but never shrunk.
2. It survives node scaling. Adding or replacing a worker does not move the volume; it stays attached to the master.

You can disable shared storage at creation time and use each node’s local disk instead. That mode is lighter, with no extra volume to pay for, but every workload that needs persistent state then has its storage pinned to whichever node it landed on.

See Storage classes and dedicated placement for more detail.

The firewall

Every cluster gets a firewall when it is created. Where the provider has a firewall Flui can drive, the rules sit at the provider’s edge. Otherwise Flui applies the Flui firewall on the machines themselves, as on a machine you brought yourself. The provider table shows which providers have one. The default rule set is small:

• HTTP and HTTPS are open, so the cluster’s public endpoints work for everyone.
• Every other port required for internal communication is reachable only on the cluster’s private network, never on the public interface.
• SSH, behind the provider’s firewall, is restricted to a source-IP list you provide at creation time (auto-detected from your current IP if you don’t pass one). Behind the Flui firewall it stays open, because a machine has no other way back in if a rule shuts you out, but it admits only certificates issued by the installation itself.

What the cluster hands back

When creation finishes, two commands tell you where you stand. flui env status reports health, nodes, service health and the effective public endpoints for the API, the dashboard and the identity provider; run it first to confirm the cluster is alive. flui env credentials shows first-access details: the bootstrap admin login for the dashboard, plus connection information for the in-cluster databases and the monitoring stack. Secrets are hidden unless you pass --show-secrets, and the bootstrap password is meant to be rotated the first time you log in.

From then on, the control cluster is operated like any other Flui cluster. It shows up in the cluster list, exposes the same surfaces (nodes, network, storage, firewall, monitoring) and accepts the same operations as a workload cluster.

This works because of a seeding step that runs the first time the API comes up: every resource the CLI created during the bootstrap (the cluster itself, its nodes, the private network, the firewall, the SSH keys) is registered in Flui’s own database. To the dashboard, the control cluster is one more row.

Workload clusters

A workload cluster is created the same way, with one difference: the control plane is not installed on it again. The identity provider, the API, the dashboard and the database live on the control cluster you already have. A workload cluster carries only the small set of components Flui adds on top of what K3s already ships: certificate lifecycle and optional cluster-side authorization.

Each node also runs host-level agents, installed at bootstrap, that push the node’s metrics and the cluster’s logs to the control cluster’s observability backend over the private network. They belong to the node rather than to the cluster’s workloads, and they make every workload cluster appear in the same monitoring views as the control cluster.

The Multi-cluster topology chapter continues from here.

Where this chapter goes from here

• Multi-cluster topology: one control cluster, many workload clusters, what they share and what they don’t.
• Nodes and cluster topology: what each node looks like once the cluster is up.
• What a cluster may buy for itself: how a cluster grows on its own, and why nothing grows until someone allows it.
• The action cycle: why an agent’s request to create a cluster stops and asks you.
• TLS and certificates: more on staging versus production, plus what happens when you bring your own domain.
• DNS integration: the path from nip.io to a real domain.