Create Clusters

Create a cluster to group nodes for high availability and data replication. After you create the cluster, Edge Infrastructure Services manages application placement and failover across the cluster nodes automatically.

​

Introduction

This procedure covers creating a three-node HA cluster, a two-node HA cluster with a tie-breaker node, and a two-node HA cluster with a witness. The steps are the same for all configurations, with differences in prerequisites and the nodes you select during creation. Every cluster you create here runs Kubernetes on its nodes. If you also want to deploy GitOps and Helm workloads to the cluster and use kubectl, turn on Enable Kubernetes Access in the Identity step, as described in this procedure. For the Kubernetes features themselves, see ZEDEDA Edge Kubernetes Service.

​

Prerequisites

​

Three-node HA prerequisites

• Nodes are running the EVE-k (EVE-OS Kubevirt) image. EVE-OS KVM is not supported.
• You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
• At least three nodes are onboarded and online.
• None of the nodes you want to add to the cluster have a default network instance. Default network instances are not supported on cluster nodes. Cluster creation fails if any selected node has one configured.
• All three nodes must use the same hardware model with a minimum of 12-core CPU, 16 GB RAM, and NVMe SSDs for EVE-OS persistent storage. Non-NVMe storage is not supported. EVE-OS uses approximately 4 GB of memory and 2 vCPUs for clustering operations.
• ZEDEDA recommends separating the management traffic from the cluster traffic, though this is not strictly required. Use a dedicated 1 Gb interface for management and a dedicated 10 Gb interface for cluster traffic. The appropriate interface size depends on your network traffic, replicated storage size, storage disk type, and workload write patterns.

​

Two-node HA with a tie-breaker prerequisites

• Nodes are running the EVE-k image version 16.0.0 or greater. EVE-OS KVM is not supported.
• You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
• At least three nodes are onboarded and online: two primary nodes and one tie-breaker node.
• The tie-breaker node is tagged with tie-breaker:true before you begin. The key tie-breaker is mandatory; the value true is recommended but any value is valid. You must assign this tag before cluster creation. You cannot add it afterward.
• None of the nodes you want to add to the cluster have a default network instance.
• The two primary nodes must use the same hardware model with a minimum of 12-core CPU, 16 GB RAM, and NVMe SSDs for EVE-OS persistent storage. Non-NVMe storage is not supported. EVE-OS uses approximately 4 GB of memory and 2 vCPUs for clustering operations.
• The tie-breaker node can use lower-specification hardware.

​

Two-node HA with a witness prerequisites

• Nodes are running the EVE-k image. EVE-OS KVM is not supported.
• You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
• Exactly two nodes are onboarded and online in the same project. Both nodes join as server nodes.
• No tie-breaker node is part of the cluster. The etcd-only witness replaces the tie-breaker, and it runs on the seed node without a separate node.
• None of the nodes you want to add to the cluster have a default network instance.

​

Enable the Clusters Feature

Enterprise entitlements control the cluster feature. If clustering is not available in your enterprise, contact your ZEDEDA sales team to have it enabled. There are two levels of control to enable the feature flags:

• Root: This is the base feature configuration. If the feature is disabled here, it’s disabled across all child enterprises.
• Child: This is for the specific enterprise. The child enterprise can enable or disable the cluster feature only if the feature is enabled in the parent enterprise.

To confirm the feature is active:

1. Log in as CSAdmin.
2. Navigate to Entitlements and select your enterprise.
3. Verify that the Storage Clustering entitlement is enabled.

If the feature is disabled at the root enterprise level, you cannot enable it in child enterprises.

​

Configure the Cluster Identity

1. Navigate to Infrastructure > Fleet > Clusters, then select the contextual + create action. The New Cluster wizard opens.
2. Enter the cluster Name. The name must be unique across the enterprise. You cannot change it after creation.
3. Enter the cluster Title. The title is a display label. You can change it at any time.
4. Enter an optional Description to explain the cluster’s purpose to other administrators.
5. Enter Tags to help group and identify clusters, for example env:production. For two-node HA, set the tie-breaker:true tag on the tie-breaker node before cluster creation (see the preceding Prerequisites section), not on the cluster itself.
6. Optionally, turn on Enable Kubernetes Access to create the cluster in ZEDEDA Edge Kubernetes Service mode. See the following section for what this setting does.
7. Select Next.

You select the cluster’s project in the next step, along with its member nodes.

​

Enable Kubernetes Access

By default, a new cluster runs in Edge mode: you deploy workloads to it as application instances. Turning on Enable Kubernetes Access exposes the cluster’s native Kubernetes so that users can also deploy GitOps and Helm workloads and use kubectl. The cluster registers with Rancher and uses extra session and memory on the member nodes. Keep the following in mind before you turn on this setting:

• Enabling Kubernetes access is permanent. You can turn the switch off while you are still in the wizard, but after the cluster is created you cannot turn Kubernetes access back off from the console.
• The switch is disabled if your enterprise does not have the Kubernetes orchestration entitlement. The wizard shows a message under the switch explaining that the feature is not enabled.
• You can also enable Kubernetes access later from the cluster detail page. See Manage Node Clusters.

The Review step shows Enable Kubernetes Access as Enabled or Disabled so you can confirm the choice before you create the cluster.

​

Select the Cluster Nodes

1. Select the cluster’s Project. The dropdown is searchable, so you can type to narrow a long project list.
2. In the Nodes list, select the nodes to include in the cluster:
   • Select 1 node for a single-node cluster.
   • Select 3 or more nodes for a high-availability cluster. For a two-node HA setup with a tie-breaker, include the tie-breaker node (already tagged with tie-breaker:true) along with the two primary nodes.
   • Select exactly 2 nodes for two-node HA with a witness, then turn on Enable two-node HA.
3. Select Next.

A two-node cluster is valid only with Enable two-node HA turned on. Without it, the wizard shows a 2-node cluster isn't supported unless you enable two-node HA below. and you cannot continue.

​

Enable two-node HA

The Enable two-node HA switch appears below the Nodes list. When you turn it on, the cluster runs on the two selected server nodes, and an etcd-only witness on the seed node provides the third quorum vote. The witness hosts no workloads. The switch is available only when you select exactly two server nodes and no tie-breaker node. Otherwise, it is disabled and the wizard shows the reason under it: If you change the node selection so that the switch becomes unavailable, Edge Infrastructure Services does not create the cluster with two-node HA. Every node in a cluster belongs to the same project, so the Nodes list shows only the nodes in the project you selected. Nodes that already belong to another cluster are not listed, because a node can be a member of only one cluster. If the project has no node you can add, the list shows either No nodes found in this project. or Every node in this project already belongs to a cluster. Changing the project clears any nodes you already selected, along with the cluster interfaces assigned to them.

​

Configure the Cluster Network

The network step shows a table of your selected nodes. Each row has a Cluster interface column where you assign the network interface that carries cluster traffic.

1. For each node row, select Choose interface in the Cluster interface column.
2. In the interface picker that opens, select the NICs, VLANs, or LAGs tab and choose the interface to use for cluster traffic. All selected interfaces must be physically connected through a Layer 2 network for the cluster to form.
3. When each node shows Ready in the Status column, select Next.

The NICs tab lists every network port defined by the node’s hardware model, not just the interfaces you have already configured. Unconfigured ports appear with the usage label Unused, so freshly onboarded nodes still offer their physical ports for selection. Each NIC also shows a run-state label of Up, Down, or Not Reporting. The run state is informational only. You can select an interface that is currently Down or Not Reporting, because applying the cluster configuration is what brings the interface into service. If a node row shows No network interfaces on this node's hardware model and None available, the node’s hardware model defines no network ports, so there is nothing to select. If the console cannot load a node’s network adapters instead, the row shows an error message with a Retry button that re-fetches the interface list.

​

Review and Create the Cluster

1. Review the cluster identity, node selection, and network configuration. If you turned on two-node HA, the review shows Two-node HA as Enabled (witness as third vote).
2. Optionally, update the Cluster-Prefix to specify a private IP range for internal cluster node communication. The cluster-prefix is the IP range allocated to the nodes within the cluster for private inter-node traffic. If you leave it unchanged, Edge Infrastructure Services assigns a prefix automatically.
3. Select Create Cluster.

The console shows the cluster as created immediately, but allow a few minutes for the cluster formation job to complete before the cluster is fully operational.

​

Verify the Configuration

Navigate to Infrastructure > Fleet > Clusters and select the cluster name to open its detail page. On the Overview tab:

• Confirm all cluster nodes show a Status of Ready in the Cluster topology section.
• Confirm the cluster Run State is Online.
• For a two-node HA cluster, confirm that the Two-node HA panel shows an HA state of Healthy and a Witness of Joined.

If nodes show Not Ready or the cluster shows Init after several minutes, check that the cluster interface ports are correctly connected through the Layer 2 network and that no default network instances exist on the selected nodes.

​

Next Steps