Single-Node Clusters

Harvester supports single-node clusters for implementations that can tolerate lower resilience or require minimal initial deployment resources. You can create single-node clusters using the standard installation methods (ISO, USB, and PXE boot).

Single-node clusters support most Harvester features, including the creation of RKE2 clusters and node upgrades (with some limitations). However, this deployment type has the following key disadvantages:

No high availability: Errors and updates that require rebooting of the node cause downtime to running VMs.
No live migration and zero-downtime support during upgrades.

Prerequisites

Before you begin deploying your single-node cluster, ensure that the following requirements are met.

Hardware: Use server-class hardware with sufficient resources to run Harvester and a production workload. Laptops and nested virtualization are not supported.
Network: Configure ports based on the type of traffic to be transmitted among VMs.

Replica Count of the Default StorageClass

Harvester uses StorageClasses to describe how Longhorn must provision volumes. Each StorageClass has a parameter that defines the number of replicas to be created for each volume.

The default StorageClass harvester-longhorn has a replica count value of 3 for high availability. If you use harvester-longhorn in your single-node cluster, Longhorn is unable to create the default number of replicas, and volumes are marked as Degraded on the Volumes screen of the Harvester UI.

To avoid this issue, you can perform either of the following actions:

Change the replica count of harvester-longhorn to 1 using a configuration file.
Create a new StorageClass with the Number of Replicas parameter set to 1. Once created, locate the new StorageClass in the list and then select ⋮ > Set as Default.

Multiple Replicas on a Node with Multiple Disks

Longhorn creates only one replica for each volume even if the node has multiple disks because Replica Hard Anti-Affinity is enabled by default. When a healthy replica already exists on a node, the scheduler is prevented from scheduling new replicas of the same volume on the node.

In high-availability clusters, Replica Hard Anti-Affinity ensures volume redundancy. However, this same mechanism can cause volumes to become degraded in single-node clusters (since no other nodes are available for scheduling of new replicas).

If you want Longhorn to create multiple replicas on a node with multiple disks, perform the following steps:

Enable Replica Node Level Soft Anti-Affinity: When this setting is enabled, Longhorn schedules new replicas on nodes with existing healthy replicas of the same volume.
Disable Replica Disk Level Soft Anti-Affinity: When this setting is disabled, Longhorn does not schedule new replicas on disks with existing healthy replicas of the same volume. Disabling this setting provides failure tolerance for disks in single-node clusters.
(Optional) Create a new StorageClass and specify the disk tags that must be matched during volume scheduling.

Upgrades and Maintenance

Single-node clusters do not support Live Migration, so VMs become unavailable during cluster upgrades. Harvester forcibly shuts down all VMs before starting the upgrade process.

Enabling Maintenance Mode is also not possible because that operation relies on Live Migration functionality, and Harvester cannot place the only control plane in Maintenance Mode.