> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/using-pipekit/clusters.md).

# Clusters

Connect multiple clusters to Pipekit, and run workflows on different Kubernetes clusters while managing access and viewing the workflow results in one central dashboard.

If your cluster does not yet have Argo Workflows installed, you can use [the Pipekit Agent](/concepts/pipekit-agent.md) to install Argo Workflows.

## Connect a Kubernetes Cluster to Pipekit

Go to the [Clusters tab in Pipekit](https://pipekit.io/clusters) and click on the `+ Connect Cluster` button.

You will be prompted to select an [organization](/organizations-and-access.md) to connect the cluster to.

Choose an appropriate name and description for your cluster. It is recommended to use a name that is all lowercase with no whitespace.

Choose which namespace you intend to install the Pipekit Agent. Common namespaces are `default` and `pipekit`, although you can choose any namespace you wish, including the namespace where Argo Workflows resides (by default, `argo`). That namespace is where the agent runs, not what it watches: an agent watches every namespace by default, and you can [scope it to a single namespace](/using-pipekit/clusters/namespaced-agent.md) instead.

Press `Submit` when you are ready to proceed.

### API Key

You will be presented with a unique API key for your cluster. You will need this API key to install the Pipekit Agent on your cluster. It will only be shown to you once, so make sure to copy it and store it somewhere safe. [You can always generate a new API key if you lose it](#generating-a-new-api-key), but this will immediately invalidate the old key.

#### Pipekit Agent Installation Options

You can install the Pipekit Agent on your cluster using either a Kubernetes YAML Manifest or [Helm Chart](/reference/helm-values/agent.md).

Your browser will have automatically downloaded the YAML manifest for you.

Once you have installed the Pipekit Agent, the `Waiting for cluster to come online` indicator will turn green and you can click `Close`.

## Clusters View

You can see all your clusters in the [Clusters tab in Pipekit](https://pipekit.io/clusters). Each cluster carries one labeled status chip per component Pipekit installs on it: `Agent` for the Pipekit Agent and `Metrics collector` for the metrics collector. Green means that component is reaching the Pipekit API, red means it is not, and gray means Pipekit has not heard from it yet. Each chip is its own health check, so a red chip says nothing about the other one. On a Pipekit Agent older than v7.6.0, the collector chip reads `Metrics collector: upgrade agent`, because those versions do not run the metrics collector. [Upgrade the Pipekit Agent](#pipekit-agent-version) to get it. If you have installed the Pipekit Agent but its indicator stays red, check the logs of the Pipekit Agent pod for errors.

If you click a given cluster, you can view all runs across all Pipes for that cluster.

### Pipekit Agent Version

The version of the installed Pipekit Agent is shown to the left of the status chips. It is important to keep your Pipekit Agent up to date, as it will ensure you have the latest features and bug fixes. The Pipekit Agent is always released alongside the Pipekit CLI and Helm chart with the same version number. You can check the latest version of the Pipekit Agent by either looking at available [Pipekit CLI](/reference/cli.md) versions, available [Helm chart](/reference/helm-values/agent.md#checking-the-latest-version) versions or by looking at the Pipekit Agent image tags on [Docker Hub](https://hub.docker.com/r/pipekit13/pipekit-agent/tags).

Moving from a `6.x` chart to `7.x` is a breaking upgrade, because `7.0.0` changed the agent to an operator-managed deployment. Refer to [Upgrading to the Operator-Managed Agent](/using-pipekit/clusters/agent-upgrade.md).

### Modifying a cluster

You can modify a cluster by clicking on the cluster name. This will take you to the cluster details page where you can navigate to the Settings tab to change the cluster name, description and API key. You can also make the cluster inactive or delete it from here. Toggling the active state on each cluster is how you trigger the [Disaster Recovery](/using-pipekit/clusters/disaster-recovery.md) failover, including the automatic queue cleanup when a cluster comes back online.

#### Generating a new API key

If required, you can generate a new API key for your cluster by clicking "Rotate API Key" on the cluster settings tab. This will immediately invalidate the old API key.

### Queuing

By default, Pipekit operates a first-in-first-out (FIFO) queue by treating the priority of all submitted workflows as the same. This means that if you submit two workflows to Pipekit, the first workflow will be submitted to your cluster before the second workflow. If you submit a third workflow, it will be submitted after the second workflow.

At scale, this may be problematic as short-running jobs may get backed up behind longer-running jobs and this may not meet your business needs. You can define priority groups for workflows at a cluster level by clicking on the cluster name and navigating to the Queuing tab.

By default, all workflows are given a priority of `3`. If you want some workflows to have a higher priority, enter an appropriate name in the Workflow Group ID field (e.g. `highest-priority`) and select `1 (Highest)` in the dropdown before saving.

Any workflows with the label `workflows.pipekit.io/workflow_group_id: "highest-priority"` running in this cluster will be given a higher priority than other workflows.

Similarly, if you wish to give some workflows a lower priority, enter an appropriate name in the Workflow Group ID field (e.g. `lowest-priority`) and select `5 (Lowest)` in the dropdown before saving. Again, any workflows with the label `workflows.pipekit.io/workflow_group_id: "lowest-priority"` running in this cluster will be given a lower priority than other workflows.

{% hint style="info" %}
The priority is given to the *submission* of the workflow and not to the pods within the workflow. For the avoidance of doubt, setting the queue priority does not increase the [Pod Priority](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/) of the pods within the workflow. This is something that should be configured in the workflow and the kubernetes cluster itself.
{% endhint %}