====== Edge Node Cluster Setup — How-To Guide ======

This guide walks you through the end-to-end process of creating and verifying an Edge Node Cluster using the ZEDEDA platform UI. Follow the steps to ensure a successful deployment.

===== 1. Overview =====

An Edge Node Cluster groups three physical edge nodes into a high-availability compute unit. All three nodes are equal cluster members with full functionality — there is no controller/worker distinction between them.

The underlying cluster infrastructure (k3s, networking, storage) is **fully managed by the ZEDEDA platform**. Customers interact only through the ZEDEDA UI workflow — no manual Kubernetes configuration or deployment is required. If one node is designated a **Witness** (tie-breaker), apply the tag **tie-breaker = true** to that node before clustering.

<WRAP center round important 80%>
**⚠️ Important — Wait Before Clustering**\\
After onboarding the 3 nodes, allow them to run for 8–10 minutes before creating the cluster. This ensures initial setup tasks complete and prevents cluster formation errors.
</WRAP>

===== 2. Prerequisites =====

Ensure all of the following are in place before proceeding:

^ ^ Requirement ^ Details ^
| ☑ | **Project** | A Project must already be created in the platform. |
| ☑ | **Network** | A Network must be created for EVE control plane networking. |
| ☑ | **3 Edge Nodes** | Three physical edge nodes fully onboarded. A single ethernet interface can be shared for control plane and cluster traffic. L2 connectivity between nodes for cluster communication. If one node is a Witness, apply the tag: ''tie-breaker = true'' |
| ☑ | **EVE-K Image Installed** | RAW image — for USB installation. ISO image — for remote installs (IPMI / ILO / iDRAC). |
| ☑ | **Node Warmup** | After onboarding, let all 3 nodes run for 3–5 minutes before clustering. |

===== 3. Create the Edge Node Cluster =====

Follow these steps in the ZEDEDA UI to create the cluster:

==== Step 1 — Open Edge Node Clusters ====

  * **Navigate** to the side menu and select **Edge Node Clusters**:

{{:zededa:edge-node-clustering:image1.png?200|}}

  * Click the **+ button** in the top-right corner of the screen to begin creating a new cluster:

{{:zededa:edge-node-clustering:image2.png|Add new cluster button}}

==== Step 2 — Enter Cluster Details ====

Fill in the cluster information form:

  * **Name** — Enter a unique name for the cluster.
  * **Title** — Enter a descriptive title.
  * **Project** — Select the correct project from the dropdown.
  * **Description** — (Optional) Enter a description.
  * **Cluster Tags** — Leave at default unless a Witness node is required.

Click **Next** to continue.

==== Step 3 — Select Edge Nodes ====

  * On the **Edge Node Selection** screen, check the boxes next to the 3 nodes you want to include in the cluster.
  * Available nodes will appear in the list below the selection area.

Click **Next** to continue.

==== Step 4 — Configure Cluster Network ====

  * On the **Cluster Network** screen, configure the network interface for each node:
  * **Expand** each member node to reveal its network adapters.
  * **Select** the correct **Network Adapter** to be used for cluster communication:

{{:zededa:edge-node-clustering:image3.png|Cluster Network adapter selection screen}}

Click **Next** to continue.

==== Step 5 — Review and Create ====

  * On the **Review & Create** screen, verify all selected settings.
  * Enter the **Cluster Prefix** — this is the IP prefix used for inter-node cluster communications (e.g., ''10.200.0.0/24''):

{{:zededa:edge-node-clustering:image4.png|Cluster Prefix input field}}

Click **Create** to provision the cluster.

===== 4. Verify Cluster Status =====

==== 4.1 Monitor via the UI ====

After creation, navigate back to **Edge Node Clusters** and select the cluster you just created. The **Cluster Run State** indicator will cycle through the following stages:

^ State ^ Description ^
| **provisioned** | Cluster configuration has been pushed to nodes. |
| **init** | Nodes are joining the cluster and initializing k3s. |
| **online** | All nodes are clustered and the cluster is fully operational. |

{{:zededa:edge-node-clustering:image5.png|Cluster status panel showing Run State}}

<WRAP center round tip 80%>
**⏱ Timing**\\
This process typically takes 3–5 minutes for all nodes to cluster and reach the Online state.
</WRAP>

==== 4.2 Optional: Real-Time Monitoring via SSH ====

<WRAP center round info 80%>
**ℹ️ Fully Managed Service**\\
The cluster setup and k3s configuration is handled entirely by the ZEDEDA platform — no manual intervention is needed. SSH access is provided here as an optional way to observe the cluster formation process in real time.
</WRAP>

To watch the cluster come online via live log output, SSH into an edge node and tail the install log.

=== Step 1 — Enable SSH and Connect ===

Follow the [[https://help.zededa.com/hc/en-us/articles/17918434708763|SSH enable procedure]] to enable SSH access and add your public key to the edge node, then connect.

=== Step 2 — Enter the Kube Control Plane ===

Once connected to the EVE shell, run:

<code>
eve enter kube
</code>

This drops you into the cluster management control plane shell.

=== Step 3 — Tail the Install Log ===

Run the following command to stream the cluster setup log in real time:

<code>
tail -f /var/log/k3s-install.log
</code>

You should see output similar to the following as the cluster forms:

<code>
2026-05-07 15:42:01 : Reapply Multus CNI for clusternodeip: 10.200.0.3
2026-05-07 15:42:01 : Cluster Node IP prefix to multus: 10.200.0.0/24 with node-ip 10.200.0.3
2026-05-07 15:42:03 : provision config file for node to cluster mode
2026-05-07 15:42:03 : config.yaml configured with Join-ServerIP 10.200.0.1
2026-05-07 15:42:03 : Check if the Endpoint https://10.200.0.1:6443 is in cluster mode...
2026-05-07 15:42:08 : Cluster transition in progress, waiting before starting k3s
</code>

===== 5. Expected Component States =====

Once the cluster reaches **online** state, the ZEDEDA platform will have automatically configured and verified all required cluster components. If you are monitoring via SSH, the log will confirm each component is ready:

<code>
Component: multus    ready on existing version
Component: kubevirt  ready on existing version
Component: cdi       ready on existing version
Component: longhorn  ready on existing version
</code>

===== Quick Reference =====

^ Task ^ Command / Location ^
| **Enter kube shell** | ''eve enter kube'' |
| **Stream cluster log** | ''tail -f /var/log/k3s-install.log'' |
| **UI: View clusters** | Side menu → Edge Node Clusters |
| **Witness node tag** | ''tie-breaker = true'' |
| **Warmup time** | 6–7 minutes after onboarding |
| **Cluster form time** | 8–10 minutes |

//End of Document//