Nodes and cluster topology
A cluster is made of nodes. This chapter covers what a node is, which role it can take, and how a cluster can change shape over time while keeping its identity.
What a node is
A node is one machine, a virtual server provisioned by the provider, that belongs to exactly one cluster and plays exactly one role in it. It carries Flui’s ownership labels from the moment it is created until it is deleted.
Each node has a stable Flui identifier, a role, a provider, a region, a server type, public and private addresses, and a direct link to the resource at the provider. For the cluster, a node is one row of capacity bound to one machine. If that binding drifts (a server deleted by hand at the provider, or removed from the cluster outside Flui), the cluster reports the inconsistency and lets the operator decide how to reconcile the two sides.
A single cloud account can hold several independent Flui
installations side by side, so listing an account’s servers does
not tell you which belong to this one. Flui classifies every
instance it sees as self (owned by this installation),
other-flui (created by another Flui installation sharing the
account) or unmanaged (never provisioned by Flui), and acts only
on the ones it owns. The dashboard shows each machine’s ownership
next to it, so you can see which ones this installation manages.
The two roles
Every cluster has one master and any number of workers.
The master coordinates the cluster: every other node talks to it. It is also a regular node where workloads can run. A small cluster works fine with a single master that also hosts applications.
Workers add capacity. They join the cluster after the master is up, take their share of the work, and can be added or removed without disturbing the master.
Two rules follow from this:
- A cluster has at least one node, and that node is the master. A master-only cluster is a valid cluster.
- On your own servers,
flui node removedetaches a machine you attached withflui node connect. On a provider Flui buys from, you give a node back by lowering the scaling group’s floor (flui scaling floor <n>), and a manual group asks you to approve the removal first. Neither ever removes the master. Taking the master out of a cluster means destroying the whole cluster, which is a separate operation in the cluster’s lifecycle.
Every cluster has a single master. Your applications do not need it to keep answering: losing it stops changes to the cluster, but traffic to what already runs continues. See High availability for what that means.
Protecting the control cluster’s master
A master that runs workloads is convenient on small clusters. On the control cluster, though, once you have workers you do not want the dashboard, API and database competing for the master with new workloads. Flui changes the master’s role automatically as the control cluster grows.
When the control cluster goes from one node to several (when the scaling group adds its first worker), Flui reserves the master for the control plane, so new workloads are placed on the workers. What it started on the master and is free to leave moves to the workers too: components that keep nothing on the master’s disk, when a worker has room for them. The API, the database and anything else that holds its data there stay. If you scale the control cluster back down to a single node, the reservation is lifted automatically, because the master is again the only place anything can run. The current state is recorded on the cluster.
This is best effort: if the reservation cannot be applied or
lifted, the scaling operation it accompanies still succeeds,
because protection never blocks a resize. You can also set it by
hand with flui env set-master-protection on|off|show, which
reports the live state and the stored flag. On a control cluster
on your own servers, this is how you do it: a machine attached
with flui node connect does not reserve the master on its own.
This applies only to the control cluster; masters of workload
clusters stay open to workloads.
Growing and shrinking a cluster
A cluster’s shape can change in two independent ways:
- Horizontally, by adding or removing workers: more or fewer machines, each of a shape the scaling group allows, or any machine of your own.
- Vertically, by changing the server type of an existing master or worker: the same machine, with more or less CPU and RAM.
Horizontal: adding and removing workers
When the scaling group buys a worker, Flui provisions a new server with the right ownership labels, joins it to the cluster’s private network, attaches it to the firewall when there is one, and waits for it to join the cluster before marking the node healthy. Existing workloads keep running, and the new worker starts receiving work once it is ready.
Removing a worker follows the same steps in reverse: the cluster stops sending new work to the node, moves the work already running on it to the other nodes, detaches it from the network and firewall, and then deletes the server at the provider. The cluster keeps serving traffic the whole time.
The scaling group gives a worker back only when it can be emptied
(no application keeps its data on it and no application’s
disruption rule refuses) and when its work fits on the machines
that stay. Otherwise the worker is kept, and the group says why.
A machine of your own detached with flui node remove gets two
minutes to empty. After that it is removed anyway, and the
operation says so.
Some workloads are easier to move than others. Applications using the cluster’s shared storage can run anywhere on the cluster and follow the work being moved off a worker. Applications that need fast local storage are pinned at deploy time to the worker with the most free room (or to the master, on a workload cluster with no worker). Their data lives on that machine, so you cannot remove a worker holding one until you back the app up and move or delete it. The trade-off is covered in Storage classes and dedicated placement, and resizing the node that holds them is the vertical case described below.
On your own servers nothing checks the room for you: if the remaining nodes cannot hold what ran on the machine you detach, that work stays unplaced until capacity returns.
Whether capacity returns on its own depends on the cluster’s
scaling group. On a provider Flui buys from, every cluster
starts with one: a manual group holding the nodes it has, so
nothing is bought until you move its floor
(flui scaling floor <n>, then flui scaling approve --yes). On
your own servers there is no scaling group. You size the cluster by attaching machines
with flui node connect or by scaling the existing ones up.
A group set to provision: automatic changes that. The group
watches for work the cluster cannot place, and when it finds some
the cluster buys a machine without being asked. It stays inside
the limits the group sets: the shapes it may buy, the regions it
may buy them in, a ceiling on how many machines it may hold, and a
spending ceiling written in money instead of node count. A group
left on provision: manual decides and tells you what it would
have bought, without acting, so you keep control of the cluster’s
shape.
Vertical: resizing a node
Where the provider supports it (see which do), a node can also be resized in place, moving from one server type to a bigger or smaller one. The platform powers the machine off, asks the provider to swap the server type, powers it back on, waits for the cluster to report it healthy, and makes it available for work again. Storage is preserved and the node keeps its identity; only its CPU and memory change.
Vertical scaling is planned maintenance: the node is unavailable
for a few minutes during the swap, and so is any workload pinned
to it. Before doing anything, the CLI shows a plan with the cost
difference and the affected workloads (flui env scale-node for a
worker, flui env scale-master for the master).
The exact commands and trade-offs for horizontal and vertical scaling are in CLI: Environments.
What stays constant when the cluster changes shape
Adding, removing or resizing nodes never changes the cluster’s identity. The cluster keeps its name, its UUID, its endpoints, its certificates, its storage and the ownership labels on every provider resource it owns. Where the provider offers the capability, it also keeps its DNS names and its firewall. Apps keep their addresses, data stays on the same volumes and users keep their sessions.
So you can refer to a cluster, and point automation at it, while the machines underneath it change.
Where this chapter goes from here
- Multi-cluster topology: how the control cluster and its workers fit into the wider installation.
- VNet and subnets: the private network every node attaches to.
- The network Flui builds: what a node attaches to when the provider supplies none.
- Firewalls: the rules that govern what can reach a node from outside.
- What a cluster may buy for itself: the group that decides whether any of this happens without you, and where it has to stop.
- Let a cluster buy its own machines: writing that group, field by field.
- CLI: Environments: the operational reference for adding, removing and resizing nodes.