Updated 29 October 2026 · Published by Zoorik
Short answer. To connect, you need a supported cluster, the right access, a new connect command, and a cluster that can reach Zoorik. Check them in the order below. Once the agent registers, the cluster appears on Overview, and its figures follow within minutes.
Check the cluster is supported
Look at: the cluster’s cloud, its Kubernetes version and its nodes.
What it means: Coral works on AKS on Azure and EKS on AWS. Other clusters connect as “Local”, without cloud prices. The cluster needs Kubernetes 1.30 or later, and at least one Linux node, on amd64 or arm64.
What to do: Make sure the cluster meets these before you connect it. A cluster that shows as “Local” still connects, but its figures have no cloud prices.
Check the command points at the right cluster
Look at: the kubeconfig context the connect command uses.
What it means: To connect, you need cluster-admin on the cluster, through a kubeconfig context.
What to do: Add --kube-context <name> to the command to pick the cluster. Run it as a user with cluster-admin.
Check the connect command is new
Look at: when you copied the command, and whether you ran it before.
What it means: The command carries a connect token. The token works only once, and only for a short time after you get it.
What to do: On Overview, open “Connect cluster” again and copy a new command. If you installed with Helm, connect again with a new token:
$ helm upgrade coral-agent \ oci://ghcr.io/getzoorik/charts/coral-agent \ --kube-context <context> --namespace default \ --reuse-values --set connectToken.value=<new connect token>
With connectToken., replace the token in the Secret, then restart the agent:
$ kubectl --context <context> -n zoorik-agent rollout restart deployment/zoorik-agent
Check your cloud tools and permissions
Look at: your cloud’s command-line tool, and your permissions in your cloud account.
What it means: zoorikctl lists every change it will make in your cloud and asks you once. To connect, you need:
| Cluster | Tool | Permissions |
|---|---|---|
AKS | The Azure CLI ( az), signed in | Owner, or Contributor with User Access Administrator, on the cluster’s subscription |
EKS | The AWS CLI ( aws), signed in | Permission to create IAM roles and EKS Pod Identity associations |
EKS, when connect installs Karpenter | Also Helm 3.8 or later | Also SQS, EventBridge and cluster updates |
What to do: Sign in, or ask for these permissions, then run the command again. To see what connect will change first, add --dry-run. It prints every cloud command and everything the agent setup installs, and changes nothing.
Check the network
Look at: what the cluster can reach on the internet.
What it means: The agent always starts the connection to Zoorik itself, over HTTPS. Nothing outside the cluster connects in. So the cluster must be able to reach these over HTTPS:
- Zoorik.
ghcr.andio pkg-containers., for the images.githubusercontent. com - Your cloud’s APIs, for node removal: Azure Resource Manager and Entra ID, or AWS STS and Auto Scaling.
What to do: Allow these, then wait for the agent’s first report.
Check what connect set up in your cloud
Look at: your answer when zoorikctl asked about the cloud changes.
What it means: If you said no, the agent still installs. Pools that an autoscaler runs are optimized as usual. Fixed-size pools wait until you give the permission to remove nodes.
On AKS, connect turns on NAP only if the cluster has no autoscaler. NAP needs Azure CNI networking and doesn’t work with kubenet. On kubenet with no autoscaler, nothing adds nodes until you set one up.
What to do: Give the permission to remove nodes when you are ready:
$ zoorikctl cluster grant-node-deletion
To set up an autoscaler later, run zoorikctl cluster prepare.
Wait for the first report
Look at: Overview, and the cluster’s own pages.
What it means: After you approve, zoorikctl installs the agent and waits for it to register. The cluster then appears on Overview, and its figures follow within minutes. Until data arrives, pages show “Waiting for the agent’s first report…”, then “Calculating”.
What to do: Keep the page open: it updates by itself. Until data arrives, figures read “Calculating” or “Fetching prices”, never a guess. If the page keeps waiting, check the network again.
Check your Helm install
Look at: your helm install command and its values.
What it means, and what to do: If you installed with the coral-agent Helm chart rather than zoorikctl, check these.
| If | What it means | What to do |
|---|---|---|
You installed into zoorik-agent or zoorik-node | The chart creates those two namespaces itself, so the install fails with an ownership error. | Install the release in any other namespace, such as default. |
The cluster was connected with zoorikctl before | Helm doesn’t own the objects zoorikctl created, so helm install won’t take them over. | Run zoorikctl cluster disconnect first. Then install the chart with a new connect token. |
controlPlaneUrl has a path or a trailing slash | It must be the base address only, exactly as the console shows it. | Remove the path and the trailing slash. |
You set connectToken. | The agent pod waits until that Secret exists. | Create it in zoorik-agent, with the token under the key bootstrap-token. |
EKS, with Pod Identity | The agent gets AWS credentials only if the association exists when its pod starts. | Create the association first. If the agent already runs, restart it once: kubectl --context <context> -n zoorik-agent rollout restart deployment/ |
helm install --wait is slow to return | It waits until the agent has stayed ready for a while. | Nothing. This is expected. |
If the cluster shows “Not reporting”
Look at: the cluster’s entry in the console.
What it means: After a disconnect, the cluster stays in the console as “Not reporting”. The data Zoorik already received stays with it.
What to do: If you disconnected it, connect it again with a new command from “Connect cluster”. If you didn’t, email us.
If the Agent release card says “Re-run connect”
Look at: the “Agent release” card on the cluster’s Dashboard.
What it means: The agent updates itself to each Zoorik release. It can’t give itself new permissions, so a release that needs more shows “Re-run connect”. An agent that Argo CD, Flux or Helm manages doesn’t update itself.
What to do: Run the connect command again. With Helm, helm upgrade to a newer chart version updates the agent.
Still stuck?
The Coral product guide and the Coral FAQ have the full detail.
Email founders@zoorik.com, or pick a time to talk (opens in a new tab). Tell us what you ran and what the console shows. Remove tokens, keys and other secrets from anything you send.