Create and Manage Kubernetes Clusters

Prerequisites

Before creating a cluster, confirm the following:

Nodes must run EVE-k (the EVE-OS variant for Kubernetes) 16.0 LTS or greater and must be onboarded to Edge Infrastructure Services.
The Kubernetes Orchestration entitlement must be enabled for your enterprise. Edge Infrastructure Services checks the entitlement at two levels: the root enterprise and your own enterprise. Both must be enabled. Enabling it at only one level leaves the feature disabled. See Admin Dashboard.
Clusters created from this page require 1, 3, or more nodes. Two-node clusters are not supported here. To run a cluster on two nodes, create it from Infrastructure > Fleet > Clusters with two-node HA enabled. See Create Clusters.

Configure the Cluster

This page describes the separate Infrastructure > Fleet > Kubernetes page, which the console shows only while your enterprise has the Kubernetes Orchestration entitlement and no cluster has yet reported its Kubernetes mode. If you do not see the Kubernetes item in the sidebar, your enterprise manages every cluster from Infrastructure > Fleet > Clusters instead. Create the cluster there and turn on Enable Kubernetes Access in the Identity step. See Create Clusters.

In the sidebar, select Infrastructure > Fleet > Kubernetes. Select the Kube Clusters tab.
Select Add Cluster.
Enter a Name. This identifier must be unique within your enterprise, and you cannot change it after creation.
Enter a Title. This is the display name shown in the cluster list.
Optionally enter a Description.
Optionally enter a Cluster Prefix (CIDR) to define the IP address range for the cluster network.
Optionally add Tags to organize the cluster for filtering and fleet management. If you plan to deploy installed applications or create cluster groupings by tag, use a consistent tag across all target clusters (for example, region:us-west).
Select Next.

Select nodes

Select a Project from the dropdown. The project determines which nodes are available to add.
In the Nodes field, select one or more onboarded EVE-k nodes to include in the cluster. This page supports single-node and 3-or-more-node clusters. Two-node clusters are not supported here. Two-node HA with a witness is available only from Infrastructure > Fleet > Clusters.
Select Next.

Review and create

Review the cluster configuration and node assignments.
Select Create Cluster. The cluster begins provisioning.

After saving, the cluster moves through the following provisioning states: Created > Initializing > Control Plane > Control Plane Ready > Joining Nodes > Online.

Import an Existing Cluster

Use Import Cluster to bring a third-party Linux Kubernetes cluster under ZEDEDA device management. Device orchestration remains your responsibility in this mode.

The Kubernetes Orchestration entitlement controls several surfaces. Without it, the console hides the Kubernetes navigation item and the Import Cluster action and omits Kubernetes and imported clusters from Infrastructure > Fleet > Clusters. The Enable Kubernetes Access control in the cluster creation wizard and on the cluster detail page stays visible but is disabled, with the explanation “Kubernetes Orchestration is not enabled for your enterprise. Contact your administrator.” An administrator can enable the entitlement to restore these controls.On the cluster detail page, this applies while the cluster is online. The control is one side of an Edge / Kubernetes switch that the console hides entirely while the cluster is offline or unprovisioned, so the disabled treatment does not appear in that state.

In the sidebar, select Infrastructure > Fleet > Kubernetes. Select the Kube Clusters tab.
Select Import Cluster.
Enter a Name. This identifier must be unique within your enterprise, and you cannot change it after creation.
Enter a Title. This is the display name shown in the cluster list.
Select a Project that the cluster belongs to.
Optionally enter a Description and Tags.
Select Import.

After importing, locate the cluster by name in the list and open its detail page. Follow the Registration instructions shown there to connect your existing cluster.

Register the cluster

The detail page displays a registration URL unique to your cluster. Run one of the following commands on your existing Kubernetes cluster, depending on your environment. Standard registration:

kubectl apply -f <registration-url>

If you get a “certificate signed by unknown authority” error (self-signed or untrusted SSL certificate):

curl --insecure -sfL <registration-url> | kubectl apply -f -

If you get permission errors (your user lacks the cluster-admin role):

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user <your-username-from-kubeconfig>

The cluster appears as registered in Edge Infrastructure Services after the command completes.

View Cluster Status

The Kube Clusters tab lists all clusters with the following columns: Name, Status, Kubernetes Version, Nodes, and Project. Select a cluster name to open the cluster detail page.

Status ribbon

The top of the detail page shows a status ribbon with six tiles:

Field	Description
Status	The current cluster status, such as Online or Offline. A secondary label such as Registered might appear below the status value.
Kube Version	The Kubernetes version running on the cluster.
Nodes	The number of nodes in the cluster. A secondary label such as configured reflects node enrollment state.
Type	The Kubernetes distribution type, such as K3S or RKE2. Shows a dash when not set.
Project	The project this cluster belongs to.
Age	How long the cluster has existed, with its creation timestamp.

Overview tab

Use Overview for a fast read of cluster health and identity. Live status shows real-time cluster health and has two sub-views:

Conditions: Lists any conditions reported by the cluster. When the cluster is healthy, this section shows No conditions reported. When conditions are present, each entry shows a status (True, False, or Unknown) and a message. A False condition indicates a component issue. Review the message and check the Nodes tab to identify the affected node.
Nodes: Lists the status of each node in the cluster.

Identity at-a-glance appears on the right side of the page and shows a summary of cluster metadata, including the cluster ID, Name, Title, Description, Kube Version, Nodes, and Created timestamp. Recent activity lists recent recorded events for the cluster, followed by the cluster lifecycle entries. Each event shows its timestamp, its severity (for example INFO, WARNING, or ERROR), and a short description of what happened. Up to 20 events are listed, and the section scrolls when the list is longer than the panel. Beneath the events, three lifecycle entries always appear: the last reported state, the last configuration update, and the project the cluster was created in. A cluster with no listed events is expected and does not indicate a problem.

Nodes tab

The Nodes tab lists each member node with the following columns: Name, Status, Serial Number, EVE-OS Image Version, and Location. Use this tab to monitor individual node enrollment and health during and after provisioning.

Details tab

The Details tab groups cluster configuration into three panels:

Panel	Fields
Identity & Ownership	ID, Name, Title, Description, Imported, Tags, and Cluster Prefix.
Connection	Cluster Type, Kube Version, ZKS Cluster ID, and Fleet Workspace.
State & Timeline	Run State, Node Count, and Created.

Live Kubernetes tabs

When the cluster is online, the following tabs appear in the tab strip alongside Overview, Nodes, and Details:

Tab	Contents
Dashboard	A live event log showing Kubernetes events for the cluster, including pod scheduling, container starts, replica scaling, ETCD snapshots, and other cluster-level activity.
Cluster	Node-level Kubernetes detail with two sub-views: Nodes (showing Name, Status, Roles, Age, Version, IP addresses, OS, and live CPU, RAM, and pod utilization) and Events (Kubernetes cluster events).
Workloads	Kubernetes workload resources, with sub-views for Deployments (the default view), Stateful Sets, Daemon Sets, Jobs, Cron Jobs, HPAs (Horizontal Pod Autoscalers), and Pods.
Service Discovery	Network exposure resources, with sub-views for Ingresses and Services.
Storage	Storage resources, with sub-views for Persistent Volumes, Storage Classes, and PVCs.
Policy	Resource governance policies, with sub-views for Limit Ranges, Network Policies, Pod Disruption Budgets, and Resource Quotas.
Configuration	Configuration resources that workloads read, with sub-views for Config Maps and Secrets.

These tabs are disabled when the cluster is offline.

Run state reference

The Run State field in the Details tab shows the current operational state of the cluster. During initial provisioning, the cluster moves through the following sequence:

Run state	Meaning
Created	The cluster record exists and is waiting to start provisioning.
Initializing	The cluster is initializing.
Control Plane	The control plane node is being set up.
Control Plane Ready	The control plane is ready.
Joining Nodes	Worker nodes are joining the cluster.
Online	The cluster is fully provisioned and operational.

After provisioning, the cluster can move into these operational states:

Run state	Meaning	Usual next check
Online	The cluster is connected and available.	Confirm node count and Kubernetes version.
Offline	Edge Infrastructure Services is not receiving communication from the cluster.	Check node power, network reachability, and EVE-OS boot state.
Healthy	All cluster components are healthy.	No action required.
Suspect	The cluster is flagged for investigation. It might still be running, but one or more components are not operating as expected.	Review the Conditions panel on the Overview tab and check individual node status on the Nodes tab.
Unhealthy	One or more cluster components are reporting issues.	Open the Nodes tab and check individual node status.
Partially Healthy	Some nodes or components are healthy but others are not.	Open the Nodes tab to identify which nodes need attention.
Error	The cluster has entered an error state.	Review recent activity and node status.
Failed	A provisioning or lifecycle operation failed.	Review recent activity and retry or delete the cluster.
Unknown	The state cannot be determined.	Wait briefly and refresh, then check node connectivity.

If you access clusters from Infrastructure > Fleet > Clusters, the list shows Name, Status, member count, Project, a mode badge (K8s Cluster), and Age. Select a cluster name to open the detail page. The detail page shows Overview, Details, and Nodes tabs, plus a Kubernetes Dashboard tab (when the cluster is online) in place of the individual Kubernetes tabs described in the preceding sections.

Configure a Cluster

You can update a cluster’s display name, description, and tags after creation. The cluster prefix (CIDR) is read-only after creation.

Open the cluster detail page, or locate the cluster in the Kube Clusters list.
Select Configure cluster from the row actions menu, or select Configure cluster in the cluster detail page header.
Update the Title, Description, or Cluster Tags fields as needed.
Select Save.

The Configure (gear) action is not currently available from Infrastructure > Fleet > Clusters, either on the cluster row or on the cluster detail page. Use the Kube Clusters pages described in the preceding steps to configure the cluster.

Upgrade the Kubernetes Version

Initiate cluster version upgrades from the cluster detail page.

Open the cluster detail page.
In the page header, open the dropdown menu and select Upgrade K8s Version.
Select a Target Version from the available options.
Confirm the upgrade.

The cluster moves through its provisioning states again during the upgrade. Monitor progress on the Nodes tab.

Kubernetes version upgrade is not available from Infrastructure > Fleet > Clusters. If you do not see the Upgrade K8s Version option described in the preceding steps, this operation might be available only through ZCLI. See ZCLI: Manage ZEDEDA Edge Kubernetes Service Clusters for cluster upgrade commands.

Download Kubeconfig

Download the kubeconfig file to access the cluster from your workstation using kubectl.

Open the cluster detail page.
In the page header, open the dropdown menu and select Download Kubeconfig.
Save the file to your workstation.
Use the file by setting the KUBECONFIG environment variable or passing it with the --kubeconfig flag when running kubectl commands.

Note: you cannot add or remove nodes that have running application instances.

If you access this cluster from Infrastructure > Fleet > Clusters, open the cluster detail page and select the Download icon button in the page header.

Open a Cluster Shell

Use the cluster shell to run kubectl commands directly from the ZEDEDA console without downloading a kubeconfig file.

Open the cluster detail page.
In the page header, select Cluster Shell.

A terminal session opens in the browser with kubectl access to the cluster.

If you access this cluster from Infrastructure > Fleet > Clusters, open the cluster detail page and select the Terminal icon button in the page header.

Delete a Cluster

In the Kube Clusters tab, locate the cluster you want to remove.
Select Delete cluster from the row actions menu.
Confirm the deletion.

Deleting a cluster removes it from ZEDEDA management. It does not delete the member nodes; they remain onboarded to Edge Infrastructure Services.

If you access this cluster from Infrastructure > Fleet > Clusters, open the cluster detail page and select the trash icon in the upper-right area.

Next Steps

Manage Installed Applications

View and manage Helm chart deployments across your clusters.

Manage Cluster Groupings

Organize clusters into logical groupings for fleet-level management.

GitOps Repositories

Connect Git repositories for automated Helm chart delivery.

Troubleshoot Edge Kubernetes

Diagnose and resolve common cluster issues.

Tagging

Tag clusters for grouping and filtering across the fleet.

Start Here

Infrastructure Services Overview

Core infrastructure

Build

Applications and delivery

Edge Kubernetes

Operations

Monitor

Administration and Security

Troubleshooting

Partnerships

Create and Manage Kubernetes Clusters

Prerequisites

Configure the Cluster

Select nodes

Review and create

Import an Existing Cluster

Register the cluster

View Cluster Status

Status ribbon

Overview tab

Nodes tab

Details tab

Live Kubernetes tabs

Run state reference

Configure a Cluster

Upgrade the Kubernetes Version

Download Kubeconfig

Open a Cluster Shell

Delete a Cluster

Next Steps

Manage Installed Applications

Manage Cluster Groupings

GitOps Repositories

Troubleshoot Edge Kubernetes

Tagging

​Prerequisites

​Configure the Cluster

​Select nodes

​Review and create

​Import an Existing Cluster

​Register the cluster

​View Cluster Status

​Status ribbon

​Overview tab

​Nodes tab

​Details tab

​Live Kubernetes tabs

​Run state reference

​Configure a Cluster

​Upgrade the Kubernetes Version

​Download Kubeconfig

​Open a Cluster Shell

​Delete a Cluster

​Next Steps

Manage Installed Applications

Manage Cluster Groupings

GitOps Repositories

Troubleshoot Edge Kubernetes

Tagging

Prerequisites

Configure the Cluster

Select nodes

Review and create

Import an Existing Cluster

Register the cluster

View Cluster Status

Status ribbon

Overview tab

Nodes tab

Details tab

Live Kubernetes tabs

Run state reference

Configure a Cluster

Upgrade the Kubernetes Version

Download Kubeconfig

Open a Cluster Shell

Delete a Cluster

Next Steps