Kubernetes

Connect a Kubernetes cluster

Connect an EKS, AKS, GKE, DOKS or self-hosted cluster without giving Zaysa a cloud key.

About 10 minutes

Zaysa reads a cluster through a connector that runs inside it. The connector signs in to the cluster with its own Kubernetes ServiceAccount and opens a connection out to Zaysa, so you store no cloud key and the cluster API never needs to be public. The same steps work on Amazon EKS, Azure AKS, Google GKE, DigitalOcean DOKS and clusters you run yourself.

Before you start

Any plan. Free includes one connector, Pro five and Business as many as you need.
A terminal where kubectl points at the cluster as an administrator, for example Google Cloud Shell after gcloud container clusters get-credentials. You need it once, to install the connector.
The cluster can open outbound HTTPS (port 443) to zaysa.io. No inbound port is needed.

Install the connector in the cluster

Add a Kubernetes connector
Open Beam → Connectors and click Add connector. (1) Choose Kubernetes. (2) Name it after the cluster, for example web-cluster. (3) Click Create.
Apply it to the cluster
Zaysa shows a block that starts with kubectl apply. Click Copy (1), paste the whole block into your terminal and press Enter.
Treat the block like a password
It contains the token that lets the connector register. Paste it only into the cluster you chose. If it leaks, delete the connector and add a new one.
Then wait for the connector to start:
Terminal
```
kubectl -n beam-system rollout status deploy/beam-connector
```
Terminal
```
deployment "beam-connector" successfully rolled out
```
In Zaysa, the connector’s card on Beam → Connectors now shows Online.

Connect the cluster

Open Connect cluster
Open Kubernetes → Overview and click Connect cluster (1).
Pick where the cluster runs
Click the card for your cloud (1), or Self-hosted for a cluster you run yourself.
Choose Keyless and your connector
(1) Keep Keyless selected. Type a Cluster Name; it is the name you will see in Zaysa. (2) Pick the connector you just installed. A connector installed a moment ago is marked new (online). (3) Click Connect & Discover.
Zaysa reads the cluster through the connector straight away and shows what it found.

Check it worked

Click Done and open the cluster. Its Read access card says Reading keyless with the connector online, and the page shows the cluster’s nodes, namespaces and health.

The web-cluster page with the risk score, Reading keyless online, cluster info and node health

To see exactly what Zaysa may do in this cluster, click Check permissions at the top right. See Check permissions.

What the connector installs

In the cluster	Why
`beam-system`	The namespace the connector and everything it creates live in.
`beam-connector` Deployment	One pod running `zaysahq/beam-connector`, pinned to an exact version and digest.
`beam-connector-read` ClusterRole	Read-only (get and list) access to nodes, pods, workloads, services, events, storage, autoscalers, RBAC objects, metrics and pod logs, and to Argo CD and Flux objects. It cannot read Secrets.
`beam-connector` ClusterRole	Only for team access through Beam: creating and removing the short-lived ServiceAccounts and bindings that give a teammate the built-in `view`, `edit` or `admin` role. It cannot grant `cluster-admin`.
`beam-connector-token` and `beam-connector-identity` Secrets	The token the connector registered with, and its own signing key, so it keeps its identity when the pod restarts. Only the connector’s ServiceAccount is given access to its key.
`zaysa-node-meta` DaemonSet	A small pod on each node that reads the node’s cloud machine type and region and adds them as labels (`zaysa.dev/instance-type`, `zaysa.dev/region`, `zaysa.dev/cloud`), so costs use the real price of each node. Its ClusterRole allows reading and updating nodes; the pod only adds these labels.

Connect with a cloud key instead

If you cannot run a connector in the cluster, choose Cloud credentials in the same window and paste a read-only key: an AWS access key for EKS, an Azure app (tenant, client ID and secret) for AKS, a service account JSON key for GKE, or a DigitalOcean token for DOKS. Zaysa stores the key encrypted. Keyless is safer, because no key exists that could leak.

If something goes wrong

The connector is not in the list

The list shows only connectors that are online. Check the pod, then its log:

Terminal

kubectl -n beam-system get pods
kubectl -n beam-system logs deploy/beam-connector --tail=50

“runs on a VM or cannot read this cluster”

That connector was installed on a Linux machine, not in a cluster, so it cannot read Kubernetes. Add a Kubernetes connector as above.

The apply fails with “forbidden”

Your kubectl user may not create namespaces or ClusterRoles. Run the block as a cluster administrator.

Remove the connector

Remove the cluster in Zaysa with Remove on its page, delete the connector on Beam → Connectors, then remove it from the cluster:

Terminal

kubectl delete namespace beam-system
kubectl delete clusterrole beam-connector beam-connector-read zaysa-node-meta
kubectl delete clusterrolebinding beam-connector beam-connector-read zaysa-node-meta

Next steps

Explore a clusterFind your way around a connected cluster: health, workloads, logs, cost, alerts and exports.Give kubectl accessGive a teammate time-limited kubectl access to a cluster, in the browser or from their own computer.Check permissionsCheck which Zaysa features your cloud connection can use and how to fix missing access.