> ## 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.

# Manage ZEDEDA Edge Kubernetes Service Cluster Groups

> Use ZCLI to generate a cluster group manifest, then create, check the status of, and delete ZEDEDA Edge Kubernetes Service cluster groups.

Use the ZEDEDA CLI (ZCLI) to manage ZEDEDA Edge Kubernetes Service cluster groups from the command line. This article covers `zcli edge-kubernetes-cluster-group` commands, with syntax and examples for each operation.

A cluster group (called a cluster grouping in the Edge Infrastructure Services console) is a named collection of ZEDEDA Edge Kubernetes Service clusters in a project. You can check the health of every member cluster, and of the resources deployed to them, in one place. A cluster belongs to a group when its tags match the labels in the group's selector. The selector is part of the cluster group manifest, a JSON document that you pass when you create the group.

Cluster groups contain ZEDEDA Edge Kubernetes Service clusters, which you create with `zcli edge-kubernetes-cluster`. See [Manage ZEDEDA Edge Kubernetes Service Clusters](https://zededa.mintlify.site/zcli-reference/kubernetes-clusters.md). Those clusters run on node clusters, which you manage with `zcli edge-node-cluster`. See [Manage Node Clusters](https://zededa.mintlify.site/zcli-reference/node-clusters.md). For the console workflow and the meaning of each status, see [Manage Kubernetes Cluster Groupings](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/manage-kubernetes-cluster-groupings.md).

## Before You Start

* ZCLI is installed and authenticated against your enterprise. See [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md).
* You have a role that allows you to manage ZEDEDA Edge Kubernetes Service resources in the project. \[TBD: confirm the minimum role required to create and delete cluster groups with ZCLI. Managing ZEDEDA Edge Kubernetes Service clusters requires the SysManager or SysAdmin role.]
* The project exists, and the clusters that you want in the group have the tags that the group selects on. See [Manage ZEDEDA Edge Kubernetes Service Clusters](https://zededa.mintlify.site/zcli-reference/kubernetes-clusters.md).

Cluster groups cannot be changed after you create them. ZCLI has no `update` command for cluster groups. To change a group, delete it and create it again.

## Generate a Cluster Group Manifest

Edge Infrastructure Services generates the cluster group manifest for you from the group name, the project, and the tags that member clusters must have.

```text theme={"dark"}
zcli edge-kubernetes-cluster-group manifest <name> --project=<project> [--tags=<key:value>...]
```

| Flag | Description |
| - | - |
| `<name>` | Name of the cluster group that the manifest is for. |
| `--project` | Required. Name of the project. |
| `--tags` | A tag that a cluster must have to belong to the group, in `key:value` format. Repeat the flag for more tags. A cluster must have every tag to match. |

Example:

```text theme={"dark"}
zcli edge-kubernetes-cluster-group manifest MY_CLUSTER_GROUP --project=MY_PROJECT --tags=site:factory-1
```

The generated manifest has the following form. The namespace is set by Edge Infrastructure Services for your enterprise and project, and `matchLabels` lists the tags that you passed.

```json theme={"dark"}
{"type":"fleet.cattle.io.clustergroup","metadata":{"namespace":"<namespace>","name":"MY_CLUSTER_GROUP"},"spec":{"selector":{"matchExpressions":[],"matchLabels":{"site":"factory-1"}}}}
```

> [!WARNING]
>
> In the current ZCLI, `manifest` retrieves the manifest but does not print it, so the command shows no output. To see the manifest, add the global `--debug` flag, and copy the `yamlContent` value from the `HTTP Response` line:
>
> ```text theme={"dark"}
> zcli --debug edge-kubernetes-cluster-group manifest MY_CLUSTER_GROUP --project=MY_PROJECT --tags=site:factory-1
> ```
>
> The `--debug` output includes your session token in the `Request-Headers` line. Do not share or save this output.

> [!NOTE]
>
> ZCLI sends each `--tags` value to Edge Infrastructure Services as a separate query parameter. Check that the `matchLabels` object in the returned manifest contains your tags before you create the group. \[TBD: confirm with engineering that the manifest endpoint applies tags passed this way. The API documents a single `tags` parameter.]

The `--help` text for this command shows examples with `--uuid` and without `--project`. Those examples fail, because `manifest` requires `--project` and does not accept `--uuid`.

## Create a Cluster Group

```text theme={"dark"}
zcli edge-kubernetes-cluster-group create <name> --project=<project> --json_manifest=<json_manifest>  [--title=<title>] [--description=<description>] [--tags=<key:value>...]
```

| Flag | Description |
| - | - |
| `<name>` | Name of the cluster group. The name must be unique in your enterprise and cannot be changed later. |
| `--project` | Required. Name of the project that the cluster group belongs to. |
| `--json_manifest` | Required. The cluster group manifest itself, as a JSON string. This flag takes the manifest content, not a path to a file. Note the underscore in the flag name. |
| `--title` | Title of the cluster group. If you leave it out, ZCLI uses the name. |
| `--description` | Description of the cluster group. |
| `--tags` | A tag for the cluster group itself, in `key:value` format. Repeat the flag for more tags. These tags label the group. They do not select its member clusters. |

Example, with the manifest passed inline:

```text theme={"dark"}
zcli edge-kubernetes-cluster-group create MY_CLUSTER_GROUP --project=MY_PROJECT --title="Factory 1 clusters" --json_manifest='{"type":"fleet.cattle.io.clustergroup","metadata":{"namespace":"<namespace>","name":"MY_CLUSTER_GROUP"},"spec":{"selector":{"matchExpressions":[],"matchLabels":{"site":"factory-1"}}}}'
```

To pass a manifest that you saved in a file, use command substitution in the ZCLI shell:

```text theme={"dark"}
zcli edge-kubernetes-cluster-group create MY_CLUSTER_GROUP --project=MY_PROJECT --json_manifest="$(cat cluster-group.json)"
```

`create` prints nothing when it succeeds. To confirm that the group exists, see [View Cluster Group Status](#view-cluster-group-status).

> [!NOTE]
>
> ZCLI does not check the project name. If the project does not exist, ZCLI still sends the request, with an empty project ID. Check the project name with `zcli project show` before you create the group. If a `--tags` value is not in `key:value` format, ZCLI prints `Please provide tag values as key-value pairs. Example: region:India` and does not create the group.

## View Cluster Group Status

```text theme={"dark"}
zcli edge-kubernetes-cluster-group status [<name> | --uuid=<uuid>]
```

| Flag | Description |
| - | - |
| `<name>` | Name of the cluster group. |
| `--uuid` | ID of the cluster group. Use instead of `<name>`. |

You must pass either a name or `--uuid`. Without either, ZCLI prints `ERROR: Please provide either Edge-Kubernetes Cluster Group name or UUID.`

Example:

```text theme={"dark"}
zcli edge-kubernetes-cluster-group status MY_CLUSTER_GROUP
```

The output shows the following information for each matching cluster group:

* The cluster group name, ID, title, project, description, state, namespace, age, and tags.
* `Cluster Readiness`, the number of ready member clusters out of the total.
* A resources summary that counts deployed resources by state: `Ready`, `Not Ready`, `Missing`, `Modified`, `Orphaned`, `Unknown`, and `Wait Applied`. For the meaning of each state, see [Manage Kubernetes Cluster Groupings](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/manage-kubernetes-cluster-groupings.md#view-grouping-status).
* A table of member clusters with the columns `Name`, `State`, `BundleReady`, `ReposReady`, `Resources`, `LastSeen`, and `Created`.

To get the full status record as JSON, add the global `--format=json` flag:

```text theme={"dark"}
zcli --format=json edge-kubernetes-cluster-group status MY_CLUSTER_GROUP
```

## Delete a Cluster Group

```text theme={"dark"}
zcli edge-kubernetes-cluster-group delete <name>
```

Example:

```text theme={"dark"}
zcli edge-kubernetes-cluster-group delete MY_CLUSTER_GROUP
```

> [!WARNING]
>
> `delete` removes the cluster group immediately. There is no confirmation prompt and no `-f` flag. The command prints nothing when it succeeds.

Deleting a cluster group does not affect the clusters that were members of the group. If no cluster group has the name, ZCLI prints `ERROR: Edge-Kubernetes Cluster <name> not found.` The message says "Cluster", but it refers to the cluster group.

## Next Steps

> [card] [Manage ZEDEDA Edge Kubernetes Service Clusters](https://zededa.mintlify.site/zcli-reference/kubernetes-clusters.md)
>
> Create the clusters, and set the tags that cluster groups select on.

> [card] [Manage Kubernetes Cluster Groupings](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-kubernetes/manage-kubernetes-cluster-groupings.md)
>
> Create and monitor cluster groupings in the Edge Infrastructure Services console.

> [card] [Manage Node Clusters](https://zededa.mintlify.site/zcli-reference/node-clusters.md)
>
> Manage the node clusters that ZEDEDA Edge Kubernetes Service clusters run on.

> [card] [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md)
>
> Install ZCLI, configure access to Edge Infrastructure Services, and sign in.