Add a Proxmox VE node
VirtConsole manages Proxmox VE nodes without installing the agent. The panel talks to the Proxmox API directly. Proxmox VE 8 and 9 are supported.
Before you begin
Section titled “Before you begin”- A working Proxmox VE 8 or 9 node, reachable over HTTPS from the management server.
- An API token from the Proxmox web interface: Datacenter > Permissions > API Tokens > Add. You need the full token in the form
user@realm!tokenid=UUID. - The management server installed.
Where to find it
Section titled “Where to find it”In the admin panel go to Infrastructure > Hypervisors.
- Click Add hypervisor. The Add hypervisor dialog opens.
- Select Proxmox VE as the connection type.
- Fill in the fields:
Fields
| Field | What to enter | Example |
|---|---|---|
| Name | A label you recognise in lists. | pve-us-east-1 |
| IP Address | The address the panel uses to reach the Proxmox API. | 203.0.113.20 |
| Group | The hypervisor group this node belongs to. The first Proxmox node in a group turns the group into a Proxmox cluster automatically. | US-East |
| Node Name | The node’s name exactly as Proxmox knows it. | pve1 |
| API Token | The full token string from Proxmox. | root@pam!virtconsole=1b4d6a2f-… |
| Fingerprint (optional) | The node’s TLS fingerprint, to pin the certificate. | leave empty |
- Click Link Proxmox Node. The dialog closes and the node appears in the hypervisors list.
What happens next
Section titled “What happens next”The panel connects to the Proxmox API, reads the node’s storage, networks and existing guests, and the node shows as online. Add more nodes to the same group to grow the cluster; no separate cluster setup is needed in VirtConsole.
Node addresses in a cluster
Section titled “Node addresses in a cluster”When you link a cluster through one entry address, the panel works out each member’s own management address, checks each one against the cluster’s own node list, and stores it on the node. Discovery of cluster members does the same. Nodes in one Proxmox group may share an address, so a cluster that is reached through a single address is accepted. If an address does not answer, the panel tries the other members of the group, and calls that change state move to another member when the request provably did not reach its node. An address that just failed is tried last for 45 seconds. To fill in per-node addresses for a cluster that was linked earlier, run vcli proxmox:resolve-node-addresses on the management server; add --group=<group id> to limit it to one group and --dry-run to see the result without saving it. The node type is fixed when you link it.
Common problems
Section titled “Common problems”- Authentication failed. The API token string is incomplete. Paste the full
user@realm!tokenid=UUIDvalue from Proxmox. - The node stays offline. The Proxmox API (port 8006) is not reachable from the management server, or the TLS certificate fails validation. Add the fingerprint if you use a self-signed certificate.