Clusters and nodes

This page covers the commands that act on a cluster as a whole, or on the machines inside it: cluster, node, server-types and ssh.

Which cluster a command is talking to

An installation has one control cluster, which runs Flui itself, and any number of workload clusters, which run only your applications.

The two kinds are stored in different places, and that decides which commands can see them. The CLI keeps a local record of the cluster it created on this machine, which is the control cluster. Workload clusters are created from the dashboard, with flui cluster create, or by an agent. They live only in the installation’s database, so the CLI has to ask the API for them.

Some commands read both, and some read only the local record:

flui cluster list, flui cluster volumes, flui cluster destroy, the flui scaling commands and flui ssh read the API too, so they see every cluster.
flui node list and flui node remove read the local record only, and flui node connect always joins the control cluster. Point the first two at a workload cluster and they answer that it does not exist.

The commands that take -c, --cluster <name|id> auto-detect the target when there is only one cluster to choose from, and refuse to guess when there is more than one.

For the control cluster’s own lifecycle (create, status, resize, destroy), use the env topic. It is the only surface that always targets the control cluster and has the operations specific to it.

`flui cluster list`

Lists every cluster of the installation: name, type (control or workload), provider, region, node count, status and id. The control cluster is printed first, since it is the one a bare flui ssh master addresses.

flui cluster list
flui cluster list --output json

Flag	Default	Effect
`-o, --output table\|json`	`table`	Output format.

If the API cannot be reached (you are not logged in, or the installation is down), the command still prints the clusters it holds locally and says that the workload clusters could not be listed. It does not show an empty list as if there were nothing there.

The JSON form prints only an allow-list of fields. The local record also holds cluster credentials, which must not reach standard output, where they could be redirected into a file or pasted into a chat.

`flui cluster create <name>`

Creates a workload cluster. It starts from the control cluster’s provider and region and joins its private network on its own when the provider needs one. --provider places it elsewhere, which the installation accepts only when the control cluster permits workloads on another provider.

flui cluster create edge
flui cluster create edge --worker-count 2
flui cluster create edge --provider hetzner --region hel1
flui cluster create edge --vnet <vnet-id> --subnet <subnet-id>
flui cluster create edge --no-wait

Flag	Default	Effect
`--provider <p>`	the control cluster’s	Where the cluster runs.
`--region <code>`	the control cluster’s, on the same provider	Region of the cluster.
`--node-size <type>`	the provider’s recommended type	Server type of every node.
`--worker-count <n>`	`0`	Workers beside the master; 0 is master-only.
`--vnet <id>`	none	Join a private network that already exists (see `flui network list`). Cannot be combined with `--network-cidr`.
`--subnet <id>`	the network’s only subnet	Subnet within `--vnet`; needs `--vnet`.
`--network-cidr <cidr>`	`10.250.0.0/16`	Address range of the Flui network.
`--no-wait`	off	Return once the creation is queued.

Without --no-wait it follows the creation, for up to half an hour.

`flui cluster destroy`

Permanently destroys a workload cluster and all its nodes. The command asks you to retype the cluster name before it proceeds, then waits up to ten minutes for it to go.

flui cluster destroy <cluster-name-or-id>
flui cluster destroy <cluster> --force                # skip confirmation
flui cluster destroy <cluster> --force --no-wait      # queue and exit

Argument / Flag	Effect
`<cluster>`	Cluster name or ID (required).
`-f, --force`	Skip the typed confirmation prompt.
`--no-wait`	Queue the destroy operation and return immediately.

The command refuses the control cluster by name. To destroy the control cluster, use flui env destroy.

`flui cluster volumes`

Removing an application takes its storage with it. A cluster can still carry storage that belongs to no living application. That storage keeps costing money, and this command is the only place that lists it.

flui cluster volumes
flui cluster volumes --output json
flui cluster volumes --remove user-a1b2c3/data-uptime-kuma-0

Flag	Default	Effect
`-c, --cluster <name\|id>`	auto-detect	Target cluster.
`--remove <ref>`	none	Delete one abandoned volume, given exactly as the listing printed it. Permanent.
`-f, --force`	off	Skip the typed confirmation of `--remove`.
`-o, --output table\|json`	`table`	Output format.

The listing is cautious, because a false positive here is someone’s data. A volume is only called abandoned when it sits in a place Flui made for applications, nothing is using it, nothing that could re-create it still exists, no living application is attributed to it, and it has been sitting there for at least fifteen minutes. Each entry prints the reason it qualified.

So a volume missing from the listing is not proof that nothing is left: the command errs on the side of leaving things alone. When the cluster’s credentials cannot be read at all, it says so instead of printing an empty list.

--remove takes one entry, exactly as the listing printed it, and asks you to type the volume’s name to confirm. The platform then re-runs the whole check on its side before it deletes anything, so a volume that has come back into use in the meantime is refused rather than removed. A deleted volume cannot be recovered.

Listing is read-only and needs access to the infrastructure area. Removing needs authority over the cluster’s machines, which is a level above reading them, so someone who can see the list may not be able to act on it.

Nodes

On a provider Flui buys from, a cluster’s machines change through its scaling group: flui scaling floor <n> raises or lowers the number of nodes, and flui scaling approve --yes carries out what a manual group proposes (see Let a cluster buy its own machines). The node topic lists the machines, and attaches or detaches machines of your own. The master is created with the cluster and goes away only with cluster destroy or env destroy.

`flui node list`

Lists every node in the target cluster, master and workers, with its id, role, status, address and name. When the master of the control cluster is reserved for the control plane, the listing says so on the master’s row.

flui node list
flui node list --cluster my-cluster
flui node list --output json

Flag	Default	Effect
`-c, --cluster <name\|id>`	auto-detect	Target cluster.
`-o, --output table\|json`	`table`	Output format.

`flui node remove`

Detaches a machine you attached yourself with node connect. The platform always works in this order: stop giving the node new work, move the work already on it to the other nodes, then remove it from the cluster. A machine Flui bought goes back through the scaling group instead (flui scaling floor). node remove refuses the master; to get rid of it, destroy the whole cluster.

flui node remove <node-id>
flui node remove <node-id> --cluster my-cluster
flui node remove <node-id> --no-wait

Take <node-id> from flui node list. The CLI checks the id against the cluster’s current nodes before queuing anything, so an unknown id fails immediately and points you back to node list instead of queuing an operation that cannot work.

The CLI waits five minutes. If the removal takes longer (the work is slow to move, or an application is slow to release its node), it returns and tells you the operation is still running; flui node list shows the final state. --no-wait skips the wait.

Argument / Flag	Effect
`<node-id>`	Node ID to remove (required, the master is rejected).
`-c, --cluster <name\|id>`	Target cluster (auto-detect when only one).
`--no-wait`	Queue and return immediately.

`flui node connect`

Flui buys machines through the scaling group. This command is for a machine you already have: it joins a Linux host to the cluster as a worker over SSH, and provisions nothing.

It applies to an installation running on your own servers. The command joins the control cluster. If that cluster was created at a cloud provider, it joins nothing and points you at flui scaling floor.

flui node connect --host 203.0.113.10
flui node connect --host 198.51.100.12 --master-ip 198.51.100.11 --node-network 198.51.100.0/24

Flag	Default	Effect
`--host <addr>`	required	Address or DNS name of the host to join.
`--port <n>`	`22`	SSH port of the host.
`--user <name>`	`root`	SSH user on the host.
`--ssh-key <path>`	`~/.ssh/id_rsa`	Private key that already authenticates to the host.
`--master-ip <addr>`	the cluster’s master address	The address the new machine uses to reach the master.
`--node-network <cidr>`	the `/24` of the detected private address	The private network the nodes share.
`--skip-precheck`	off	Do not inspect the host first.
`--best-effort`	off	Continue even when the inspection reports problems.

Before it starts, the command lists the three conditions the host must meet: you can reach it over SSH with the key you named, it can reach the cluster’s master on the shared private network, and it is a clean machine with no cluster software on it.

It then inspects the host and reports what it found: operating system, architecture, memory and processors. An unsupported architecture, less than about 2 GB of memory, or a cluster runtime already installed each count as a problem, and the command stops instead of joining a host that would misbehave later. --best-effort proceeds anyway, and --skip-precheck skips the inspection. Neither is meant for normal use.

When it finishes, it prints the new node’s name and private address. Run flui node list to confirm.

`flui node logs <operation>`

Prints the install log of a node an operation is creating (a new cluster’s first node, or one added node), and with -f, --follow keeps printing until the operation ends. The operation id comes from the command that added the node, flui operation, or flui scaling why.

flui node logs <operation-id>
flui node logs <operation-id> --follow

Flag	Default	Effect
`-f, --follow`	off	Keep printing until the operation has finished.
`--interval <s>`	`3`	Seconds between reads while following.

Recovery and maintenance

`flui cluster rebuild <cluster> --to <cluster>`

Re-creates the applications of a cluster that is gone, onto one that is alive, from Flui’s records and the backups. --plan shows what would happen and stops. See Rebuild a lost cluster for the full procedure.

`flui cluster rebuild-control`

Brings back the applications of the old control cluster after a platform backup has been restored into a new installation. See Rebuild the control plane.

`flui cluster recover-access <cluster> [<node>]`

Gets you back into a node whose SSH is closed, through its provider rather than its network. <node> is a server name or id, and defaults to the master. Without --yes the command only says what it would do. On OVHcloud the node is rebooted into a rescue system, the Flui firewall is reset on its disk, and it boots again with the firewall re-applied. On Hetzner and Scaleway, port 22 is opened on the provider firewall to one address (yours by default, or the one you give with --source-ip) until you remove it. A machine you brought yourself is recovered from its own console.

flui cluster recover-access hz-cluster worker-1 --yes

`flui cluster host-firewall <cluster>`

Shows, or turns on or off (--on, --off), the Flui firewall on the nodes of a workload cluster; --json prints the state as JSON. It applies where the provider’s own firewall filters in front of the nodes (see the providers table): this adds the same rules on each node, so one left outside the provider firewall still exposes only SSH, HTTP, HTTPS and the Flui network. Flui turns it on when it creates the cluster; a cluster that does not have it stays off until you turn it on.

`flui cluster enrol-overlay`

Brings an existing cluster onto Flui’s private management tunnel. It restarts the cluster software on the cluster’s first node to reissue its certificate, and puts the node back exactly as it was if it does not come up. It asks first; --yes skips the confirmation.

flui cluster enrol-overlay --cluster workload-1

Private networks

A cluster’s nodes talk to each other over a private network. Most providers get one when the first cluster is created; on a provider that needs one before a cluster can exist, you create it first.

`flui network list`

flui network list
flui network list --provider hetzner
flui network list -o json

Lists each network with its range, the provider it lives on (or built by Flui), its state and id. Under each network are the subnets a cluster can be attached to, with the ids that flui cluster create --vnet and --subnet take.

`flui network create`

flui network create --provider ovh --zone GRA
flui network create --provider hetzner --zone eu-central --ip-range 10.60.0.0/16

Flag	Default	Effect
`--provider <name>`	none	Required. The provider to create the network on.
`--zone <zone>`	the provider’s only zone	The network zone. Left out where there are several, you are shown the choices.
`--ip-range <cidr>`	`10.60.0.0/16`	The network’s range.
`--subnet-range <cidr>`	the whole range	The range of its first subnet.
`--name <name>`	`<provider>-<zone>-<suffix>`	The network’s name. The suffix is there because providers refuse a duplicate name and an installation may want more than one network in a zone.

It creates a resource on the provider’s account.

Server types

`flui server-types list`

Lists the machines a provider sells, with CPU, memory, disk and monthly price. Read it before you pick a size, for a new installation or before resizing an existing node, so that the size you ask for exists.

flui server-types list --provider hetzner
flui server-types list --provider hetzner --region fsn1
flui server-types list --provider scaleway --memory 8-32
flui server-types list --provider scaleway --sort memory
flui server-types list --provider ovh --region GRA
flui server-types list --provider hetzner --json
flui server-types list --provider hetzner --force-refresh

Flag	Default	Effect
`-p, --provider hetzner\|scaleway\|ovh`	required	Which provider’s catalogue to read.
`-r, --region <code>`	none	Filter by region or location code.
`-m, --memory <expr>`	none	Filter by memory in GB: `16` exactly, `8-32` a range, `8-` a minimum, `-32` a maximum.
`-s, --sort price\|memory\|cores\|disk\|name`	`price`	Sort key.
`--desc`	off	Sort descending.
`--json`	off	Machine-readable output.
`--force-refresh`	off	Skip the local cache and re-read from the provider.

Results are cached locally and the command says when the cache expires. --force-refresh goes back to the provider.

SSH access

`flui ssh <cluster>/<node>`

Opens a shell on a node. You do not set up a key: for each connection the CLI makes a throwaway key pair, has it signed for five minutes by the certificate authority the active profile manages, uses it, and cleans up afterwards. Nothing long-lived is left on the machine you connected from.

The argument names a node, and it takes two forms:

flui ssh master                      # the control cluster
flui ssh worker-1                    # the control cluster
flui ssh workload-cluster-1/master   # any cluster, by name
flui ssh workload-cluster-1/worker-2

A bare node name means the control cluster. Put a cluster name in front of it, separated by a slash, and you can reach any cluster of the installation, including the workload clusters that only exist in the installation’s database.

Argument	Effect
`<cluster>/<node>`	Node of a named cluster.
`<node>`	Node of the control cluster.

The node part accepts master, worker-N, or a node’s own server name as shown by flui node list. If you name a cluster that does not exist, the error lists the available clusters and their nodes. If you name an unknown node, it lists that cluster’s nodes.

On an installation running on your own server, the address, port and user recorded when it was installed are used; otherwise the connection is root on port 22.

SSH is the lowest-level surface Flui exposes. Use it for direct shell work such as debugging, looking at system processes or one-off inspection. For everyday operations (metrics, logs, restarts, deploys), use the higher-level commands; you should not need a shell for them.

Where to go from here

Add a cluster and give it capacity: the same ground as a task, with the dashboard and agent paths alongside the CLI.
Nodes and cluster topology: what a node is, and what stays constant when a cluster changes shape.
Remove an application and its data: the removal that takes the storage with it.
CLI: Environments: the control cluster’s own lifecycle.