Skip to main content

​
Introduction

ZCLI provides a complete set of commands for creating and managing ZEDEDA Edge Kubernetes Service clusters. Use ZCLI when you need to automate cluster operations, manage clusters from a script, or perform actions not yet available through the console. All ZCLI cluster commands follow the pattern zcli edge-kubernetes-cluster <subcommand>.

​
Prerequisites

  • ZCLI v19.2.x or greater is running. See Get Started for installation and authentication instructions.
  • One or more nodes are onboarded to Edge Infrastructure Services.
  • All nodes are in the same project.
  • All nodes are online.
  • Nodes are running EVE-k (EVE-OS Kubevirt) v16.0.0 or greater. EVE-OS KVM is not supported.
  • Nodes used for cluster installation have a minimum of 12-core CPU, 16 GB RAM, and NVMe SSDs for EVE-OS persistent storage. Non-NVMe storage is not supported.
  • EVE-k consumes approximately 4 GB of memory and 2 vCPUs per node for clustering operations.
  • You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
  • The node cluster feature is enabled in your enterprise. Contact your ZEDEDA sales team if it is not available.

​
Create a Cluster

Create a new ZEDEDA Edge Kubernetes Service cluster and assign nodes to it. Each node entry must specify the node name and the cluster interface separated by a colon.
Example:
ZCLI currently does not send the --title and --description values to Edge Infrastructure Services, so the cluster is created without them and the title is set to the cluster name. Use --tags to label the cluster.

​
Create a Cluster Record Without Nodes

Create a cluster record in a project without adding any nodes to it. Add nodes later with the add-nodes command.
Example:
As with create, ZCLI currently does not send the --title and --description values for import. The title is set to the cluster name.

​
Add Nodes to a Cluster

Add one or more nodes to an existing cluster. Each node entry must specify the node name and cluster interface separated by a colon.
Example:

​
Remove Nodes from a Cluster

Remove one or more nodes from an existing cluster.
This command uses the deprecated /zks/instances API path, which is scheduled for removal on 2026-12-01. It is the only way to remove a node from a cluster: the console and the /cluster API add nodes but do not remove them. After the sunset date, replace the node or delete the cluster instead. A cluster that is not two-node HA cannot drop below three nodes.
Example:

​
Generate a Kubeconfig

Generate a kubeconfig file for a cluster. Use this file to authenticate and interact with the cluster using standard Kubernetes tooling such as kubectl.
Example:

​
Update Tags

Update the tags on an existing cluster. Tags are key-value pairs used for identification and grouping.
Example:

​
Delete a Cluster

Delete an edge Kubernetes cluster. When a cluster is deleted, every node in the cluster reboots and reconfigures itself to operate as a standalone node.
Example:

​
Upgrade the EVE-k Image on a Cluster

Upgrade the EVE-OS (Edge Virtualization Engine) image on each node in a cluster. Using this command upgrades one node at a time, ensuring the cluster remains operational during the upgrade.
Example:

​
Upgrade the K3s Version

Upgrade the K3s (lightweight Kubernetes) version on a cluster. Run this command only in offline mode during a scheduled maintenance window. K3s terminates immediately on each node as part of the upgrade process, so the cluster is temporarily unavailable during the upgrade.
Example:

​
View Cluster Status

View the current status of a cluster.
The show command is an alias for status. The response payload for show might diverge from status in a future release.
Example:

​
View Cluster Metrics

View resource utilization metrics for a cluster and its nodes.
Example:

​
View Available K3s Versions

View the K3s versions available for a cluster.
Example:

​
View Registration Commands

View the registration commands required to join additional nodes to a cluster.
Example:

​
Next Steps

Create Clusters

Create a cluster using the console.

Manage Clusters

Console-based cluster management.

App Instance Failover in Clusters

Understand how applications behave during node failures.

Overview

All ZCLI command procedures, organized by resource type.