Nodes and cluster topology
A cluster is made of nodes. This chapter looks at the cluster from the inside: what a node is, what role it can take, and how a cluster’s shape can change over time without losing its identity.
What a node is
A node is one machine — a virtual server provisioned by the provider — that belongs to exactly one cluster, plays exactly one role inside it, and stays accountable to Flui’s ownership labels from the moment it is created until the moment 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 back to the resource at the provider. From the cluster’s point of view, the node is one row of capacity bound to one machine. If that binding ever drifts — a server deleted by hand at the provider, or removed from the cluster outside Flui — the cluster surfaces the inconsistency and lets the operator decide how to bring the two sides back into agreement.
The two roles
Every cluster has one master and any number of workers.
The master coordinates the cluster — it is the node every other node talks to — and at the same time it is a regular schedulable node where workloads can run. Small clusters are perfectly happy with a single master that also hosts applications.
Workers exist to add capacity. They join the cluster after the master is up, take their share of pods, 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. Master-only is a real, valid cluster.
- The node-level remove operation only acts on workers. Taking a master out of a cluster means destroying the cluster as a whole, which is a different operation altogether — and belongs to the cluster’s lifecycle, not to its node-level changes.
High-availability multi-master setups are not supported today; when they arrive, they will be a deliberate choice at cluster creation, not a silent change to the existing single-master shape.
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 of the same kind.
- Vertically, by changing the server type of an existing master or worker — the same machine, with more CPU/RAM.
Horizontal: adding and removing workers
Adding a worker provisions a new server with the right ownership labels, joins it to the cluster’s private network, attaches it to the firewall when one is present, and waits for it to join the cluster before declaring the node healthy. Existing workloads keep running throughout; the new worker simply becomes available for scheduling once it is ready.
Removing a worker reverses that journey in the correct order: the cluster first stops sending new work to the node, then moves the work already running on it onto the other nodes, detaches it from the network and firewall, and only then deletes the server at the provider. The cluster keeps serving traffic throughout, and the applications’ own disruption rules are respected during the move.
Not every workload is equally movable. 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 placed directly on the master at deploy time — so they never sit on a worker to begin with and a worker removal does not touch them. The trade-off is the subject of Storage classes and dedicated placement, and the operation that does affect those workloads — resizing the master — is the vertical-scaling case described below.
Removing a worker only makes sense if the remaining nodes have enough capacity to take on the movable share of what was running on it. If the cluster is already running close to its limit, the work that cannot fit elsewhere will stay un-scheduled until capacity returns — either by adding another worker or by scaling the existing ones up. Flui does not auto-grow the cluster to make room for what is being evicted; sizing the cluster correctly is the operator’s responsibility.
Vertical: resizing a node
A node can also be resized in place — moved from one server type to a bigger (or smaller) one. The platform powers the machine off, asks the provider to swap the underlying server type, powers it back on, waits for the cluster to report it healthy, and uncordons it. Storage is preserved; the node keeps its identity; only its CPU and memory change.
Vertical scaling is a planned-maintenance operation: the node is unavailable for a few minutes while the swap happens, and any workload pinned to that node is unavailable with it. The CLI shows a plan with the cost delta and the affected workloads before doing anything; the dashboard exposes the same flow.
The hands-on side of horizontal and vertical scaling, with the exact commands and trade-offs, is covered 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, its control-plane labels on every provider resource it owns — plus, where the provider exposes the capability, its DNS records and its firewall. Apps keep their addresses; data stays on the same volumes; users keep their sessions.
This is what makes “the cluster” a stable object to talk about and to point automation at. The machines underneath are interchangeable; the cluster is not.
Where this chapter goes from here
- VNet and subnets — the private network every node attaches to.
- Firewalls — the rules that govern what can reach a node from outside.
- CLI: Environments — the operational reference for adding, removing and resizing nodes.