← Documentation

Connecting clusters

Kaja works with your own infrastructure. You bring your clusters; we don't sell or host them. Connect each one to Kaja so you can develop and deploy from one dashboard — projects, apps, logs, metrics. This page explains how to add your clusters and what to expect.

Kaja runs on Kubernetes. Each cluster you connect is a standard Kubernetes cluster — managed cloud (EKS/GKE/AKS), on-prem, k3s, or a local k3d cluster for trying things out. See Architecture for how Kaja's concepts map to Kubernetes.

What you need

  • A Kubernetes cluster to connect (or a way to create one — k3d spins up a local cluster in seconds).
  • The Kaja CLI, and a kubeconfig context pointing at the cluster you want to connect. You do not need kubectl or Helm — the CLI talks to Kubernetes directly.
  • Permission to install into the cluster (the agent creates a namespace, default kaja, and runs there).

How to add a cluster

kaja cluster attach

It asks what to call the cluster, registers it, and installs the agent into whatever kubectl currently points at — in one run. Pass --context to choose a different one, and --name to skip the question.

Because registering and installing happen together, a cluster cannot end up recorded in Kaja with no agent in it. That was the most common way setup used to go wrong.

The command waits for the agent to connect and tells you when it has. After that you develop and deploy from the dashboard — on the infra you brought.

The agent token

Each cluster gets a token that is the agent's entire identity: there is no separate cluster id, and nothing to configure by hand. An agent holds cluster-admin on your cluster, so the token is treated like a password.

Kaja stores only its hash. The plaintext exists in exactly one response — the one that creates it — and the CLI consumes it in the same process that asked for it. It is never displayed, never pasted, and never left in your shell history.

It does not expire, and it is not consumed by first use: the agent presents it on every connection. That is why it is never written down anywhere. If you need to replace one — because it may have been exposed, or because you are reinstalling — reissue it and reinstall in one step:

kaja cluster reconnect <name>

The old token stops working immediately. There is no way to recover a token after the fact, because nothing anywhere is holding it.

Adding more clusters

You can connect as many clusters as you have. Run kaja cluster attach once per cluster, with kubectl pointing at each; every one gets its own token.

All clusters in the same organization show up in one place. Switch between them in the UI; each can have its own projects and apps. Your infra, one place to develop and deploy.

What you can do next

Once a cluster is connected you can:

  • Create projects (e.g. staging, prod).
  • Deploy apps, and add managed services (databases, caches, tools) from the catalog.
  • Pause projects or apps when you're not using them to save cost.

Next steps

  • Quick start — End-to-end from sign-in to first connected cluster.
  • Installation — What the agent does and how the install command works.