Clusters

Purpose

• Connect and provision physical Proxmox VE clusters onto the platform.
• Assign each cluster's compute, storage and NIC-function quotas so tenants can consume it.
• Map physical network connectivity (L2 interfaces, virtual bridges, L3 interfaces) to platform NIC functions.
• Review each cluster's hosts, storage devices, bridge functions and patch schedule.

Prerequisites

• Clusters are a root-account-only feature and live in the Platform section, which is hidden for tenant and child accounts.
• Minimum permission to view: platform.clusters.managed.read
• Permission to add or provision a cluster: platform.clusters.managed.create
• Permission to rescan or manage NIC functions: platform.clusters.managed.update (managing NIC functions also requires networking.vnets.create)
• A reachable Proxmox VE host IP address and its root password for the cluster you are onboarding.

View clusters

See every configured cluster and open one.

1. Open Platform → Clusters (root account only).
2. Review the Cluster Overview grid: each card shows the cluster name, total cores, total CPU (GHz), total RAM, host count and storage-device count.
3. Click a cluster card to open its Details tab (Hosts, Storage Devices, Bridge Functions and Patching Schedule).
4. Switch between the Details, NIC Functions, Manage Patching and Monitoring tabs.
5. Expected result: the selected cluster's detail loads with its hosts and storage summarised in the card titles.

Add and provision a cluster

The onboarding wizard scans a host, then walks through confirm, compute, storage, networking and configure steps.

1. Open Platform → Clusters and click Add Cluster.
2. On the Connect to a Cluster form, enter the Proxmox VE Host IP Address and Root Password, then click Scan Cluster.
3. The IP is validated and rejected if it is already configured in another cluster; discovery then runs and can be tracked on the Tasks view.
4. Confirm step: review the discovered cluster(s) and continue.
5. Compute step: map the cluster's compute quotas.
6. Storage step: map the cluster's storage.
7. Networking step: assign NIC functions to the discovered bridges and L3 interfaces.
8. Configure step: review and assign the quotas, then save.
9. Expected result: quota assignment is queued and the new cluster appears on the Clusters overview.

Manage NIC functions and physical connectivity

Inspect the network topology and assign platform NIC functions to interfaces.

1. Open Platform → Clusters, open a cluster, then select the NIC Functions tab.
2. Review the Network Interface Topology table: L3 Interfaces (routed), Virtual Bridges, and L2 Interfaces (physical NICs).
3. Click Rescan NICs to re-scan a host's physical interfaces; this queues a NIC scan task and refreshes the topology.
4. Click Manage NIC Functions to open the assignment form.
5. Toggle each L3 interface or virtual bridge on and pick a NIC Function from the dropdown.
6. At least one virtual bridge must have a NIC function assigned before you can save.
7. Expected result: saved functions appear on the Details tab under Bridge Functions.

Best Practices

• Run cluster onboarding from the root account only; tenant and child accounts cannot see or manage clusters.
• Use a reachable host IP and its root credentials, and never reuse an IP already configured in another cluster.
• Rescan NICs after any cabling or interface change before assigning or re-checking NIC functions.
• Keep at least one virtual bridge assigned a NIC function so the cluster has usable networking.
• Put a host into Maintenance from the Details tab before rebooting or shutting it down.