ZCLI: Create and Manage Edge Node Clusters

Updated

Introduction

After you create an edge node cluster, you can manage it. This article explains how to manage edge node cluster instances using ZEDEDA CLI, including creation, updates, and deletion commands, with examples for each action.

 

Prerequisites

ZCLI v14.5 is running. 

This is a series of articles. You will likely follow them in this order.

  1. Edge Node Cluster Overview
  2. Create an Edge Node Cluster 
  3. Manage an Edge Node Cluster
  4. Use the ZEDEDA CLI to Manage an Edge Node Cluster - You are here!
  5. Edge Node Cluster App Instance Failover Behavior 

Create an Edge Node Cluster

Create an edge node cluster from ZCLI.

zcli edge-node-cluster create <name> --project=<project> --nodes=<node_name:cluster_interface>... [--title=<title>] [--description=<description>] [--tags=<key:value>...] [--cluster_prefix=<cluster_prefix>]
Example
zcli edge-node-cluster create MY_CLUSTER --project=MY_PROJECT --nodes=MY_NODE1:eth2 --nodes=MY_NODE2:eth2 --nodes=MY_NODE3:eth2

View Edge Node Cluster Status

After you create an edge node cluster, you can show the status.

zcli edge-node-cluster status [<name> | --uuid=<uuid>] [--raw]
Example
 zcli edge-node-cluster status MY_CLUSTER

Update an Edge Node Cluster

After you create an edge node cluster, you can update the identity details, replace an edge node with a new node, or use EVE Kubernetes (K3s) overrides whenever things change.

zcli edge-node-cluster update <name> --nodes=<node_name:cluster_interface>... [--title=<title>] [--description=<description>] [--tags=<key:value>...][--config="k3s.version:v<a.b.c>"] [--config="k3s.config.override:<encoded-string>"]
Example

The following example shows how to add a new node to a cluster.

zcli edge-node-cluster update MY_CLUSTER --nodes=MY_NODE1:eth2 --nodes=MY_NODE2:eth2 --nodes=MY_NEW_NODE:eth2
Example: Kubernetes version override

The EVE config property of k3s.version enables you to define the Kubernetes version of edge node clusters through ZCLI EVE config properties, on a per-edge-node basis, without updating EVE-k. The property expects a properly formed k3s version string, for example: v1.34.3+k3s1. Supported with EVE-OS 16.7.0 and greater. 

The following example shows how to use the EVE K3s version upgrade override. This should only be used in offline mode during a maintenance outage window, as Kubernetes will immediately terminate on the node, download the new version, and restart.

#Should only be done in offline mode during a maintenance outage window.
zcli edge-node-cluster update MY_CLUSTER --config="k3s.version:v1.34.2+k3s1"
Example: Kubernetes config override

The EVE config property of k3s.config.override enables you to override default options for edge nodes. The property expects a base64 encoded string representing the contents of a yaml file with config additions to k3s, which is written to /persist/vault/k3s-user-override.yaml by pillar/zedkube. Supported with EVE-OS 16.5.0 and greater. 

The following example shows how to use the EVE K3s config override. This should only be used in offline mode during a maintenance outage window, as Kubernetes will immediately terminate on the node, download the new config, and restart.

Example file:

#Config override exampe yaml file text
node-label:
  - "region=earth"

Example encoding command: 

#linux
% cat config-override-nodelabel.yaml | base64

Example response:

#linux
IyBDb25maWcgT3ZlcnJpZGUgZXhhbXBsZQpub2RlLWxhYmVsOgogIC0gInJlZ2lvbj1lYXJ0aCIK

Example zCLI command: 

#Should only be done in offline mode during a maintenance outage window.
zcli edge-node-cluster update MY_CLUSTER --config="k3s.config.override:IyBDb25maWcgT3ZlcnJpZGUgZXhhbXBsZQpub2RlLWxhYmVsOgogIC0gInJlZ2lvbj1lYXJ0aCIK"

 

Add or Delete an Edge Node

Adding or deleting an edge node to or from the cluster is not supported. Only replace is supported.

Delete an Edge Node Cluster

After you add an edge node cluster, you can delete it if you no longer need it. When the edge node cluster is deleted, every node in the cluster reboots and reconfigures itself to a single node mode.

zcli edge-node-cluster delete <name>
Example
zcli edge-node-cluster delete MY_CLUSTER

Upgrade an Edge Node Cluster

After you add an edge node cluster, you can upgrade the EVE-OS image on each node. It’s necessary to update EVE-OS from a single operation on the edge-node-cluster level instead of the 'edge-node eveimage-update' operation to ensure only one cluster node is taken down at a time.

zcli edge-node-cluster upgrade <name> --image=<image>
Example
zcli edge-node-cluster upgrade MY_CLUSTER_INST --image=XXXXXXX

View Edge Node Cluster Upgrade Status

After you upgrade an edge node cluster, you can view the status of the upgrade. Note that an upgrade could potentially take hours to complete, depending on how much data needs to be transferred between nodes to rebuild replicated cluster volumes which only reside on a single remaining replica on the node in question. Node operations are blocked when a clustered volume has no replica redundancy. This is further defined in the Edge Node Cluster App Instance Failover Behavior.

zcli edge-node-cluster show [<name> | --uuid=<uuid>] [--upgrade]
Example
zcli edge-node-cluster show MY_CLUSTER --upgrade

This outputs a table of each node with a series of columns: NodeID, UpgradeableEveOS, Status, CreatedAt, UpdatedAt.

Next Steps

This is a series of articles. You will likely follow them in this order.

  1. Edge Node Cluster Overview
  2. Create an Edge Node Cluster 
  3. Manage an Edge Node Cluster
  4. Use the ZEDEDA CLI to Manage an Edge Node Cluster - You are here!
  5. Edge Node Cluster App Instance Failover Behavior

After you’ve completed the series, you might be interested in the following articles. 

Was this article helpful?
0 out of 0 found this helpful