Skip to content
Kapten
Esc
↑↓navigate↵open⌘Jpreview
On this page

Connect a cluster

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 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:

Create the service account

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

Create its token

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

Write the kubeconfig

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

Check it

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

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

Connect it

Open Clusters

In the Kapten console, open Clusters, then Connect cluster.

Describe the cluster

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

Wait for the agent

The cluster shows Bootstrapping while Kapten installs its agent, then Connected. You can now create 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.

Was this page helpful?