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

# Connect your own cluster

> Connect a Kubernetes cluster you already run with one Helm command, check that it is online, see what Ankra may do on it, and remove it again.

At the end of this guide a cluster you already run (EKS, GKE, AKS, k3s, kind, minikube or on-premises) is connected to Ankra through the Ankra agent. Connecting takes about a minute once the things below are in place. Ankra then reads the cluster and deploys nothing until you ask.

## Before you start

* **A payment method on the organisation.** Ankra asks for a card before a first cluster of your own. Saving it charges nothing, and the first 30 worker vCPUs are free. Without one, Ankra refuses to add the cluster: **Ankra connects a cluster only for an organisation with a payment method on file. Free credit does not replace it: without one, adding the cluster is refused.** The guide below lets you save the card on the way. See [Billing](https://docs.ankra.ai/platform/billing.md#credit-and-payment-method).
* **`helm` and `kubectl` on a computer that reaches the cluster.** The account your `kubectl` uses must be allowed to create a namespace and cluster-wide roles.
* **Outbound network access** from the cluster to `platform.ankra.app` on port 443 (the Ankra API), `command.platform.ankra.app` on port 4222 (the channel Ankra sends work over, TLS) and `registry.ankra.cloud` on port 443 (the agent image and its chart). Nothing inbound is needed.
* **A default StorageClass**, if you will deploy anything that keeps data. Without one, a volume that an add-on asks for stays `Pending`. Check before you start: the class marked `(default)` is the one new volumes get.

  ```bash theme={null}
  kubectl get storageclass
  ```

## Connect the cluster

**1. Choose Connect my own cluster**

On **Where do you want to start?** (`/next/onboarding`), under **Connect my own cluster**, press **Connect my cluster**. On a phone the choice says **Needs your computer: email yourself the step**, because the command runs in a terminal.

**Check:** the heading reads **Connect your cluster**. Next to **Name in Ankra:** is a suggested name. Press the pen beside it to change it.

**2. Say what the cluster runs**

Under **What does this cluster run?**, choose one:

* **Production**: Ankra AI never changes it without asking. People and their agents still can.
* **Development or testing**: you may later let Ankra AI restart or scale things unasked. That stays off until you turn it on.

**Check:** the page shows the install command, or asks for a card first.

**3. Save a card, if the page asks**

When your organisation has no payment method yet, the page says **Ankra asks for a card before a first cluster of your own.** and shows the command without its token and version, so you can read it first. Press **Save a card**, add the card, and come back.

**Check:** the command now carries your install token. The page said **Your install token appears once it is saved.**

**4. Run the install command**

Optional: type your cluster's context under **kubectl context**. It pins every command on the page to that one cluster, so none can run against another.

Copy the command exactly as the page shows it and run it in your terminal. It installs the Ankra agent with Helm and carries your cluster's token and the agent version. Its shape is:

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --version <version> \
  --set config.ankra_url=https://platform.ankra.app \
  --set config.token=<your-cluster-token> \
  --namespace=ankra --create-namespace
```

> [!WARNING]
>
> The command carries your cluster's token, a credential that does not expire. Running it leaves the token in your shell history and in Helm's release values, where `helm get values` shows it. Replacing it with `ankra cluster agent token --generate`, or removing the cluster from Ankra, ends the old one.

**Check:** the page says **Waiting for** *your cluster's name* **to connect**. It usually connects within a minute. **Check now** looks again at once.

**5. Check it is online**

**Check:** the heading changes to *your cluster's name* **is connected**, with **Ankra installed its own agent and changed nothing else.** Press **Show me** next to **See what runs on** *your cluster* **and what needs attention**.

Under **What to do next**, **Open my cluster** opens its page in Ankra, where its connection reads **Connected**.

## What Ankra can now see and do

The **What it installs, and how to remove it** fold on the page says the same, in full.

| | |
| - | - |
| **What is installed** | In the namespace `ankra`: one Deployment (`ankra-agent`), its Service, two service accounts and its Secret. Cluster-wide: one ClusterRole and one ClusterRoleBinding, both named `ankra-agent-ankra`. No DaemonSet, no CRDs, no webhooks. |
| **Its rights** | Full admin rights on the cluster: a ClusterRole that allows every verb on every resource and URL, bound to the Ankra agent. Ankra operates the cluster through it, and the agent's chart offers no narrower role. |
| **The network** | Outbound only. The agent calls out, and Ankra sends work back over that same connection. Nothing is opened inbound, and Ankra holds no kubeconfig. |
| **Its token** | A lasting credential that does not expire. The agent keeps it on the cluster in the Secret `ankra-identity-secret`, in the namespace `ankra`. It stops working when you replace it (`ankra cluster agent token --generate`) or remove the cluster from Ankra. Because the command ran in your terminal, the token is also in your shell history and in Helm's release values, where `helm get values` shows it. |
| **After it connects** | Ankra reads the cluster and its metrics, and keeps its own agent up to date. You can turn the agent updates off for this cluster. Ankra deploys nothing and changes nothing else until you ask. |
| **Production or not** | On a cluster marked **Production**, Ankra AI never changes anything unasked and findings are ranked at production severity. On one marked **Development or testing**, nothing changes by itself either, until you allow it. |

To see everything the chart would create before you install it, without applying anything:

```bash theme={null}
helm template ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent --namespace ankra
```

> [!WARNING]
>
> An AI agent you connected with **Read and change** acts as you, so it reaches this cluster too. Marking the cluster **Production** does not stop it. The connected page says so and offers **Manage its access**. See [Connect your AI agent](https://docs.ankra.ai/get-started/connect-your-ai-agent.md).

## Put a first add-on on it

[Quickstart, step 2](https://docs.ankra.ai/get-started/quickstart.md#2-deploy-your-first-stack) deploys Grafana as a Stack. It works the same on your cluster. If the chart asks for a volume, it uses the default StorageClass from [Before you start](#before-you-start).

## Verify

In Ankra, the cluster's page shows its connection as **Connected**. From the CLI, select the cluster and list its storage classes through the agent:

```bash theme={null}
ankra cluster select <cluster-name>
ankra cluster get storageclasses
```

The list matches what `kubectl get storageclass` shows on the cluster.

## Remove it again

Removing a cluster has two halves: in Ankra, and on the cluster.

**1. Remove it from Ankra**

On the connected page, open **Not the one you meant? Remove it** and press **Remove it from Ankra**. This opens the cluster's **Settings → Terminate or remove**.

Removing it from Ankra ends the Ankra agent's access at once and deletes nothing on the cluster. The agent stays installed until you take it out.

**2. Take the agent out of the cluster**

```bash theme={null}
helm uninstall ankra-agent -n ankra
kubectl delete namespace ankra
```

**Check:** nothing cluster-wide is left. This answers `NotFound` for both once it is gone:

```bash theme={null}
kubectl get clusterrole,clusterrolebinding ankra-agent-ankra
```

## What can go wrong

When nothing arrives for a while, the page says **Nothing from** *your cluster's name* **yet** and keeps watching. Open **See why: three commands, and what usually stops it** for these commands:

```bash theme={null}
kubectl get pods -n ankra -l app.kubernetes.io/name=ankra-agent
kubectl describe pod -n ankra -l app.kubernetes.io/name=ankra-agent
kubectl logs -n ankra deploy/ankra-agent
```

| What you see | What it means |
| - | - |
| The pod stays `Pending` or cannot pull its image | The `describe` line says why. |
| The pod keeps restarting | The `logs` line says why. |
| The pod runs and nothing arrives | The cluster cannot reach Ankra. Check the outbound access in [Before you start](#before-you-start). |
| Helm stopped with a permissions error | The account that ran it must be allowed to create a namespace and cluster-wide roles. |

[Ankra agent](https://docs.ankra.ai/concepts/cluster-agent.md) covers the agent in more depth.

## Other ways to connect

Outside the first screen, open **Infrastructure → Clusters** and press **Connect a cluster**. **Connect an existing cluster** has two tabs: **Install the agent** (name the cluster, then **Get the install command**) and **Find a managed cluster**. [Add a cluster](https://docs.ankra.ai/guides/import-cluster.md) covers both, and clusters Ankra builds for you.

## Where to go next

> [card] [Deploy your first Stack](https://docs.ankra.ai/get-started/quickstart.md#2-deploy-your-first-stack)
>
> Grafana on your cluster, then a question to Ankra AI about it.

> [card] [Put your app online](https://docs.ankra.ai/get-started/put-your-app-online.md)
>
> From a GitHub repository to a live address.

> [card] [Keep it in Git](https://docs.ankra.ai/concepts/gitops.md)
>
> Connect a repository so every change is reviewed and versioned.

> [card] [What Ankra can access](https://docs.ankra.ai/security/overview.md)
>
> The agent, the data Ankra keeps, and how to restrict it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.