> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Create and Manage Kubernetes Clusters

> Create, import, configure, and delete Kubernetes clusters at the edge using ZEDEDA Edge Kubernetes Service.

## 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](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/admin-dashboard.md#entitlements).
* 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](https://zededa.mintlify.site/new-ui/infrastructure-services/node-clusters/create-node-clusters.md#enable-two-node-ha).

## Configure the Cluster

> [!NOTE]
>
> 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](https://zededa.mintlify.site/new-ui/infrastructure-services/node-clusters/create-node-clusters.md#enable-kubernetes-access).

1. In the sidebar, select **Infrastructure > Fleet > Kubernetes**. Select the **Kube Clusters** tab.
2. Select **Add Cluster**.
3. Enter a **Name**. This identifier must be unique within your enterprise, and you cannot change it after creation.
4. Enter a **Title**. This is the display name shown in the cluster list.
5. Optionally enter a **Description**.
6. Optionally enter a **Cluster Prefix (CIDR)** to define the IP address range for the cluster network.
7. 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`).
8. Select **Next**.

### Select nodes

1. Select a **Project** from the dropdown. The project determines which nodes are available to add.
2. 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**.
3. Select **Next**.

### Review and create

1. Review the cluster configuration and node assignments.
2. 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.

> [!NOTE]
>
> 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.

1. In the sidebar, select **Infrastructure > Fleet > Kubernetes**. Select the **Kube Clusters** tab.
2. Select **Import Cluster**.
3. Enter a **Name**. This identifier must be unique within your enterprise, and you cannot change it after creation.
4. Enter a **Title**. This is the display name shown in the cluster list.
5. Select a **Project** that the cluster belongs to.
6. Optionally enter a **Description** and **Tags**.
7. 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:**

```bash theme={"dark"}
kubectl apply -f <registration-url>
```

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

```bash theme={"dark"}
curl --insecure -sfL <registration-url> | kubectl apply -f -
```

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

```bash theme={"dark"}
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](#run-state-reference), 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. |

> [!NOTE]
>
> 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.

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

> [!NOTE]
>
> 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.

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

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

> [!NOTE]
>
> 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](https://zededa.mintlify.site/zcli-reference/kubernetes-clusters.md) for cluster upgrade commands.

## Download Kubeconfig

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

1. Open the cluster detail page.
2. In the page header, open the dropdown menu and select **Download Kubeconfig**.
3. Save the file to your workstation.
4. 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.

> [!NOTE]
>
> 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.

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

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

> [!NOTE]
>
> 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

1. In the **Kube Clusters** tab, locate the cluster you want to remove.
2. Select **Delete cluster** from the row actions menu.
3. 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.

> [!NOTE]
>
> 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

> [card] [Manage Installed Applications](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/manage-kubernetes-installed-applications.md)
>
> View and manage Helm chart deployments across your clusters.

> [card] [Manage Cluster Groupings](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/manage-kubernetes-cluster-groupings.md)
>
> Organize clusters into logical groupings for fleet-level management.

> [card] [GitOps Repositories](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/create-gitops-repositories.md)
>
> Connect Git repositories for automated Helm chart delivery.

> [card] [Troubleshoot Edge Kubernetes](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/troubleshoot-edge-kubernetes.md)
>
> Diagnose and resolve common cluster issues.

> [card] [Tagging](https://zededa.mintlify.site/new-ui/start/tagging.md)
>
> Tag clusters for grouping and filtering across the fleet.