Adding a Hypervisor Node

A hypervisor node is a physical machine that runs your customers' virtual servers. Bringing one online means installing the panel's agent on it, letting the panel confirm the machine can actually host virtual machines, and registering it as a cluster. This article covers the whole path, what the panel checks before it accepts a machine, and how to recover a node whose agent has gone.

Where nodes live in the panel

There is no Nodes tab. The module's tab strip has seven tabs — Overview, Clusters, All VPS, Groups, Game Hosting, Jobs and Settings — and nodes are listed and managed on the Clusters tab, because the panel calls a registered machine a cluster. Everything in this article happens on that tab or in the form the Create menu opens onto it. For the tab itself — its columns, filters and per-node settings — see Clusters.

Before you start

The panel does not build a server for you. You supply a machine that already meets these conditions:

• A 64-bit Linux server with hardware virtualisation available and enabled in its firmware.
• The KVM virtualisation stack installed and running — the panel's own message names the packages it looks for: qemu-kvm and libvirt. The panel can install these for you (see below); if you install the agent yourself, install them first.
• Inbound SSH reachable from the panel, with a root login — a password or a private key. SSH is the only inbound access the install needs.
• An outbound path to the panel over HTTPS. Everything after the install is pulled by the agent, so a node behind network address translation works without any inbound rule.
• A correct clock. The panel installs a time-synchronisation service as part of the hypervisor role; a node whose clock drifts badly will refuse to run virtual-machine work.
• Somewhere to put disks — a volume group, a directory, or a storage dataset. The panel reads what exists; it does not create or convert storage for you.
• A network bridge. Nodes report the bridges they have; the module uses one of them for guest interfaces.

Warning: add an empty machine this way. The install writes packages and one service unit to the node. A machine that already runs another virtualisation panel should be brought in through VPS Panel Migration instead, which adopts its running machines rather than starting from nothing.

Adding a node

Open the Create menu on the module's tab strip and pick Node. It takes you to the Clusters tab with the Add Cluster form already open. The form starts with a choice — How to add this node:

• New node — install the agent over SSH — the panel connects to the machine and does everything.
• Existing agent — you have already installed the agent; pick it from a list.

Installing over SSH

Fields on the SSH install form

Field	What it does
Name	What this node is called throughout the panel. Choose something you would recognise in an alert, for example kvm-node-01.
IP address or hostname	Where the panel connects to install the agent.
SSH port	Defaults to the standard port; change it if the machine listens elsewhere.
SSH user	The account used for the install. It needs root privileges — the install adds packages and a service.
Authentication	Choose Password or Private key, then fill in the matching field. Credentials are stored encrypted, in the same way the agent installer stores them elsewhere in the panel.
Location	Which of your sites the machine is in. Leaving it empty is allowed but has consequences — see the warning below.
Migration pool	The group this node joins. If you leave it empty and the node has a location, the panel puts it in that location's group, creating that group the first time it is needed.

Click Install agent & add node. The install takes roughly 3 to 15 minutes — package installation on the node, then waiting for its first check-in. You can close the window; the install continues and the node appears in the list when it finishes.

Progress is shown as named stages, with the install log underneath:

1. Queued
2. Installing the agent — the agent plus, for this role, the KVM stack and a time-synchronisation service.
3. Waiting for the agent — the node must check in and report that it can run virtual machines.
4. Registering the cluster — the licence check happens here.
5. Waiting for the licence certificate — the node cannot run virtual-machine work until it holds a valid certificate naming it.
6. Reading the node inventory — storage pools, bridges and hardware totals.
7. Done, or Failed with the reason.

Warning: a node with no location also gets no group, and a node in no group is excluded from every plan that targets groups — and from live migration. Always set a location unless you have a specific reason not to. See Groups.

Using an agent you installed yourself

If the agent is already on the machine — for example you installed it from Local Agents with the Hypervisor (KVM/libvirt) role — choose Existing agent and pick it from the list, then set the name, location and group and click Add Cluster.

Only agents that qualify are listed. The note under the picker states the rule: only online agents that report they can run virtual machines are offered, and there is one cluster per node. If the list is empty you will see one of two messages:

• No eligible agents — the agent must be online and must report that it can run virtual machines. Install the KVM stack on the node and wait for the next check-in, which happens about every 30 seconds.
• Every hypervisor agent already hosts a VPS cluster — every qualifying agent is taken. Install the agent on another machine, or decommission a cluster to free its agent.

What the panel checks before it accepts a node

Registration is refused, with the reason, when any of these fails:

• The agent exists and is online. An offline agent is refused outright.
• The agent reports it can run virtual machines. This is not something you tick — the agent works it out on the node and reports it at each check-in.
• The agent does not already host a cluster. One node is one cluster; the panel names the existing cluster in the refusal.
• Your licence covers another cluster. Frozen clusters and clusters shared with you by another panel do not count towards the total.

A node is created with the status Provisioning and moves to Active once it has been read and holds a valid licence certificate. Until then it will not accept virtual-machine work.

Reading a node's inventory

Registration triggers an inventory read, and you can repeat it at any time from the node's row menu with Refresh inventory. The read fills in the node's storage pools and their free space, its network bridges, and its CPU, memory and disk totals.

Run it again after you add storage or a bridge to a machine — nothing in the panel discovers new hardware on its own. A node that has never been read reports no storage pool, and the create-machine form will tell you so.

How the agent keeps itself up to date

The agent checks in with the panel roughly every 30 seconds. Each reply carries the version the platform expects. When the agent is behind, it downloads the new version, replaces itself and restarts — you do not upgrade nodes by hand, and there is no version to choose.

Two things make this safe to leave alone:

• An update waits for work to finish. If long virtual-machine operations are running, the agent stops taking new ones, lets the current ones complete and restarts when it is idle.
• There is a platform-wide switch. If a release misbehaves, automatic updating can be turned off for every agent from Local Agents, and an agent can be reinstalled from the same page.

Running virtual machines are not affected by an agent restart. The agent manages the hypervisor; it does not run the guests.

When a node stops answering

If a node's agent goes offline, the panel marks the cluster Unreachable and shows a banner on it: the hypervisor cannot be reached, running machines are unaffected, and management resumes when the agent reconnects. The Overview tab raises this as an alert, naming the node.

Work through it in this order:

1. Check the machine is powered on and reachable on the network.
2. Check the agent service is running on the node and can reach the panel over HTTPS outbound.
3. Check Local Agents for the agent's own status and its install log.
4. If the node is genuinely gone, use Re-point agent below.

Re-pointing a node's agent

Re-pointing binds a cluster — and every virtual-machine record on it — to a different agent. Nothing is sent to either agent and no virtual machine is touched; it is a bookkeeping move for a node whose original agent no longer exists, for example after you rebuilt the operating system on the same hardware.

It is offered only while the node is unreachable or in maintenance. A node that is answering is not stranded, and re-pointing it would leave two agents driving the same machines. You must type the cluster name to confirm. Two things change afterwards:

• The licence certificate is re-signed for the new agent.
• The group's key mesh goes stale, because the new host's key is not in it — live migration stays refused until the mesh runs again. See Groups.

If no free online agent exists, the panel says so: install the agent on the replacement machine, or decommission the cluster that already holds the agent you want.

Taking a node out of service

Three levels, from lightest to heaviest:

• Drain (stop new VPS) — existing machines keep running and stay fully manageable; nothing new is placed here. Reverse it with Accept new VPS. Both can be applied to several nodes at once from the Clusters list.
• Maintenance — set on the node's Settings section with an optional reason and an expected return time. Both are shown wherever the node is listed. The window ending does not clear the flag by itself; the banner turns red so that somebody deals with it.
• Decommission — removes the cluster and frees its agent for another registration. You must type the cluster name. It is refused while any virtual-machine record still exists on the node, and the message tells you how many; delete or migrate them first.

Tip: drain a node before a planned reboot. New orders then land elsewhere while the machines already on it keep running and stay manageable throughout.

Where to go next

• Clusters — the node list, its health readings and its per-node settings.
• Groups — grouping nodes so plans can target them and machines can move between them.
• Agent Jobs — what the panel has asked this node's agent to do, and what it answered.