---
title: Connect a cluster
description: Give Kapten access to a Kubernetes cluster in your cloud account with its kubeconfig, and check that the agent is installed.
---

Kapten deploys into [clusters](/concepts/clusters) you own. Connecting one takes a kubeconfig file and a few minutes while Kapten installs its agent.

## Requirements

- A Kubernetes cluster, on AWS, Google Cloud or any other provider.
- `kubectl` access to the cluster with rights to create a service account and bind it to `cluster-admin`, since Kapten installs its agent with it.
- The cluster's API server must be reachable from the internet.

## Create a kubeconfig for Kapten

The kubeconfig your cloud CLI writes (`aws eks update-kubeconfig`, `gcloud container clusters get-credentials`) gets its token by running a local command, such as `aws` or `gke-gcloud-auth-plugin`, which Kapten cannot run. Give Kapten a service account of its own instead, with a long-lived token. Run these commands with your usual `kubectl` context pointing at the cluster:

1. **Create the service account**

    ```bash
    kubectl create namespace kapten-access
    kubectl create serviceaccount kapten --namespace kapten-access
    kubectl create clusterrolebinding kapten --clusterrole cluster-admin --serviceaccount kapten-access:kapten
    ```

2. **Create its token**

    ```bash
    kubectl apply -f - <<YAML
    apiVersion: v1
    kind: Secret
    metadata:
      name: kapten-token
      namespace: kapten-access
      annotations:
        kubernetes.io/service-account.name: kapten
    type: kubernetes.io/service-account-token
    YAML
    ```

3. **Write the kubeconfig**

    ```bash
    SERVER=$(kubectl config view --minify --output jsonpath='{.clusters[0].cluster.server}')
    CA=$(kubectl get secret kapten-token --namespace kapten-access --output jsonpath='{.data.ca\.crt}')
    TOKEN=$(kubectl get secret kapten-token --namespace kapten-access --output jsonpath='{.data.token}' | base64 --decode)

    cat > kapten-kubeconfig.yaml <<YAML
    apiVersion: v1
    kind: Config
    clusters:
      - name: cluster
        cluster:
          server: $SERVER
          certificate-authority-data: $CA
    users:
      - name: kapten
        user:
          token: $TOKEN
    contexts:
      - name: kapten
        context:
          cluster: cluster
          user: kapten
    current-context: kapten
    YAML
    ```

4. **Check it**

    ```bash
    kubectl --kubeconfig ./kapten-kubeconfig.yaml get nodes
    ```

To revoke Kapten's access later, delete the `kapten-token` secret.

> **Warning**
>
> A kubeconfig is a credential to your cluster. Keep the file out of your repository and delete your local copy once the cluster is connected.

## Connect it

1. **Open Clusters**

    In the [Kapten console](https://app.kapten.io), open **Clusters**, then **Connect cluster**.

2. **Describe the cluster**

    Enter a name, choose the cloud provider (**AWS**, **GCP** or **Custom**), and upload the kubeconfig file.

3. **Wait for the agent**

    The cluster shows **Bootstrapping** while Kapten installs its agent, then **Connected**. You can now create [environments](/concepts/environments) on it.

## Replace the kubeconfig

When the credentials change, open the cluster's menu, choose **Edit cluster**, and upload the new kubeconfig. Kapten syncs the agent with it. Leave the file empty to keep the current one.

## Troubleshooting

If the cluster shows **Bootstrap failed**, Kapten could not install its agent:

- Check that the kubeconfig works on its own: `kubectl --kubeconfig ./kapten-kubeconfig.yaml get nodes`.
- Check that it holds a token, not an `exec` section that runs a local command such as `aws` or `gke-gcloud-auth-plugin`.
- Check that the API server accepts connections from outside your network.

Then upload a corrected kubeconfig, or **Sync** the cluster to try again.
