Skip to content
flui.cloud

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.

Because a single cloud account can hold several independent Flui installations side by side, simply listing an account’s servers is not enough to know which belong to this one. Flui classifies every instance it sees as one of self (owned by this installation), other-flui (created by another Flui installation sharing the account) or unmanaged (never provisioned by Flui at all), and it only ever acts on the ones it owns. When you run flui app list, the app each instance belongs to is shown as its own SLUG column, so it is obvious at a glance what a given machine is running.

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.

Protecting the control cluster’s master

The master being a schedulable node is convenient on small clusters, but on the control cluster it has a downside: you do not want the dashboard, API and database competing for the master with arbitrary new workloads once you have workers to spare. So Flui shifts the master’s role automatically as the control cluster grows.

When the control cluster crosses from single-node to multi-node — the moment its first worker joins — Flui marks the master as reserved for the control plane, so newly scheduled workloads land on the workers instead. Anything already running on the master is left in place; only future placement is affected. Scale the control cluster back down to a single node and the reservation is lifted automatically, because the master is once again the only place anything can run. The current state is recorded on the cluster.

This is best-effort by design: if the reservation cannot be applied or lifted, the scaling operation it rides along with still succeeds — protection is never allowed to block a resize. You can also drive it by hand with flui env set-master-protection on|off|show, which reports the live state and the stored flag. This applies only to the control cluster; workload-cluster masters 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 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

  • 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.
  • Firewalls — the rules that govern what can reach a node from outside.
  • CLI: Environments — the operational reference for adding, removing and resizing nodes.