Coral product guide

1. Connect

   One command installs the Coral agent in your cluster. The command asks before it changes anything in your cloud.

2. Watch

   The agent reads usage every 30 seconds and sends 5-minute summaries. Figures appear within minutes.

3. Recommend

   Coral works out the right size for every workload, the nodes you don’t need, and what that saves.

4. Optimize

   Coral empties spare nodes for your autoscaler to remove. When you switch on automation, it also applies the new sizes.

1. Sign in

   Go to zoorik.com/login, choose Coral, and continue with Microsoft or Google.

2. Open “Connect cluster”

   On the Overview page, click “Connect cluster”. Node optimization and Workload optimization start switched on. Workload optimization only recommends until you switch on “Automatically optimize”. For a careful start, read “Stay in control” before you continue.

3. Install zoorikctl

   macOSLinuxWindows

   $ brew tap getzoorik/tap
   $ brew trust getzoorik/tap
   $ brew install zoorikctl

   Copy

4. Run the connect command

   Copy it from the dialog. Add --kube-context <name> to pick the cluster. Its connect token works once and expires after 60 minutes.

   $ zoorikctl cluster connect --connect-token="zoorik_v1_…" --api-region="us"

   Your own command, with its one-time token, comes from the console’s “Connect cluster” dialog.

5. Approve the cloud changes

   zoorikctl lists every cloud change and asks once. It then installs the agent and waits for it to register. The cluster appears on Overview, and its figures follow within minutes.

• On AKS, the OIDC issuer can’t be turned off again once it is on.
• On an EKS cluster that uses only aws-auth, installing Karpenter switches authentication to API_AND_CONFIG_MAP. That can’t be undone.
• If you decline the cloud changes, the agent still installs. Pools run by an autoscaler are optimized as usual. Fixed-size pools wait until you run zoorikctl cluster grant-node-deletion.
• To set up an autoscaler later, run zoorikctl cluster prepare.

Rebalancing pools are created later, and are labelled coral.zoorik.com/owned-by=rebalancing.

• The agent updates itself to each Zoorik release, and rolls back a failed update.
• It can’t widen its own permissions. A release that needs more shows “Re-run connect” on the Dashboard’s “Agent release” card.
• If Argo CD, Flux or Helm manages the agent, the agent doesn’t update itself.

Workload optimization

Node optimization

Cluster

While data arrives, pages show “Waiting for the agent’s first report…” and then “Calculating”. They update by themselves.

• CPU (balanced policy): the 80th percentile (P80) of the last 3 days, plus 10%.
• Memory (balanced policy): the highest use in the last 8 days, plus 10%.
• A usage surge or an OOM kill raises the size within minutes.
• With a CPU-based HPA, Coral picks the request by replaying past load through your HPA’s own settings.
• Your manifest is never changed. Coral sizes pods as they start. It applies a new size by resizing running pods in place on 1.33+ nodes, or else by restarting them one at a time.

• “Create scaling policy” starts from balanced. You can change the percentile (up to P99.9 or max), headroom, look-back (3 hours to 8 days), minimums and maximums, limits, startup CPU and rollout.
• Assign it by namespace names (patterns such as prod-.*), namespace labels, workload kinds or workload labels.
• Custom policies are checked top to bottom, and the first match wins.

Coral uses the first of these that applies:

1. Zoorik’s own namespace, and add-ons labelled addonmanager.kubernetes.io/mode: Reconcile, always get readonly. Other kube-system workloads, EKS add-ons included, follow the steps below.
2. A policy named in the workload’s coral.zoorik.com/configuration annotation (see Per-workload settings).
3. A policy picked on the workload’s page.
4. The first custom policy whose rules match.
5. The default for its kind.

Add the coral.zoorik.com/configuration annotation to the workload. Set only what you want to change.

metadata:
  annotations:
    coral.zoorik.com/configuration: |
      scalingPolicyName: stability
      vertical:
        optimization: on
        cpu:
          target: p95
          min: 250m
        memory:
          max: 4Gi
        excludedContainers:
          - istio-proxy
      horizontal:
        optimization: off

A workload with this annotation is managed from its manifest, so its console controls are locked.

• Coral creates an HPA only for a Deployment or Argo Rollout that has none. The workload needs 24 hours of history, at least 100m CPU per pod, and 2 or more ready replicas. The new HPA’s minReplicas is 2 or more.
• It takes over only HPAs nothing else manages. It keeps minReplicas, only raises maxReplicas, and restores your values on “Hand back”.
• It never changes HPAs from Helm, Argo CD, Flux, KEDA or kubectl apply.
• With automation on, Coral switches an active VPA to Off, and restores it when you switch off.
• Switching automation off removes the HPAs Coral created and hands back the ones it took over.

• Coral uses pod requests to work out how many nodes each pool needs. Every pool keeps at least one node.
• Before it moves anything, the agent checks on the live cluster that every pod on the node fits on another Ready node.
• It cordons and drains one node at a time. If a drain can’t finish in 10 minutes, the node goes back into service.
• After “Wait before removing empty nodes” (5 minutes by default), Coral hands the empty node to your autoscaler, whose own timers decide when it goes. Coral deletes the machine itself only in fixed-size pools that nothing else manages.
• Pools that Karpenter or NAP already consolidates are left to them.

• Moves pods off lightly used nodes, in pools where empty nodes get removed. It never deletes a machine and never overrides a PodDisruptionBudget.
• Runs inside your cluster and checks every 60 seconds by default.
• On from install, with its own switch in Settings → General. Switching off Node optimization does not stop it.
• “Dry run” lists the nodes it would empty in the Event log, without moving any pod.

Coral moves a pod in the first of these ways that works:

1. Warm handover: a replacement pod starts and becomes Ready on another node, then the old one is evicted.
2. Live migration: where both nodes passed a live-migration check, the pod is checkpointed and restored on the other node. Clients see a short pause, longer for pods with more memory.
3. Eviction: within the pod’s PodDisruptionBudget.

Warm handover isn’t possible for StatefulSets, Argo Rollouts, workloads with the Recreate strategy, pods with ReadWriteOnce volumes, GPU pods or HPA-scaled pods. Without live migration, these pods get a short restart.

A held node is one Coral won’t empty, because a pod on it can’t be moved safely. Node list → “What’s holding them” shows each reason and its fix. The common ones:

Rebalancing replaces the nodes you choose with cheaper machines that still fit the work.

• Needs: Karpenter or NAP, Node optimization on, and the permission to remove nodes.
• Steps: “Prepare new plan” → choose nodes → “Generate plan” → compare current and rebalanced cost → “Rebalance”. A plan expires after 1 hour.
• How it runs: Coral creates fixed-size NodePools named zoorik-rb-…. Your Karpenter or NAP launches the new machines. Then the old nodes are drained and removed one by one. The new pools stay after the run.
• “Evict nodes gracefully” is off by default. While it is off, pods still on a node after 20 minutes of normal eviction are deleted, even if their PodDisruptionBudget doesn’t allow it. Switch it on to keep such a node instead.
• Schedules: a schedule runs every day at 02:00 UTC and starts a rebalance by itself when its savings target is met.

• A PodDisruptionBudget that allows no disruption keeps its pods, and their node, in place for consolidation and the Evictor. A rebalance respects it only when “Evict nodes gracefully” is on.
• The ignore label stops workload changes only (sizes and HPAs). It does not stop node moves.

1. For recommendations only at first, switch off Node optimization in the Connect dialog. The Evictor still starts with the agent and can move pods, so do step 2 as soon as the cluster appears.
2. Open the Evictor’s “Advanced settings” in Settings and tick “Dry run”.
3. In Configuration → Node pools, switch off the pools you don’t want touched.
4. Create a scaling policy for one namespace, set its Optimization type to “Vertical”, and switch on “Automatically optimize”.
5. Watch the Event log and the Impact page, then widen step by step: more namespaces, more node pools, and Node optimization back on.

• Prices are the cloud’s published list price for the region, refreshed nightly. Spot nodes are priced at the spot rate.
• Discounts, reservations and savings plans are not included. A month is 730 hours.
• Until data exists, figures read “Calculating” or “Fetching prices”, never a guess.

• Usage summaries per container: CPU, memory, OOM kills, probe failures and CPU pressure, in 5-minute windows.
• An inventory every 5 minutes: nodes, namespaces, workloads with their requests and limits, autoscalers, PodDisruptionBudgets, quotas, and up to 64 labels per workload and namespace.
• Events, with pod and node names: OOM kills, probe failures, spot interruptions, and Coral’s own actions, including the pods the Evictor moved.
• A heartbeat every 60 seconds.
• At registration, the cloud account: the Azure subscription and resource group, or the AWS account and region.

• The agent can’t read your Secrets or ConfigMaps, and has no pods/log, pods/exec or pods/portforward permission. It holds get on nodes/proxy to read kubelet metrics. That permission can also reach the kubelet’s log and exec endpoints, which Coral never calls.
• No env var values, commands, image names or request payloads are sent. The only event text sent is the message when a pod can’t be created because of a quota, a limit range or an admission policy.

• The agent opens every connection to Zoorik itself, over HTTPS, and accepts none from outside the cluster. Inside it, the API server calls the webhook, and the node daemons talk to each other over mutual TLS.
• The connect token works once, for 60 minutes. The agent swaps it for a cluster credential that rotates by itself.
• Admission policies limit the agent’s changes. For example, it may scale a Deployment by only one replica, and change only the HPAs and NodePools Coral manages.

• zoorik-node runs privileged on every Linux node, so it can checkpoint and restore containers.
• A checkpoint holds the pod’s memory, secrets included. It stays inside your cluster, moves between the two nodes over mutual TLS, and is deleted when the move ends.

Sign in with Microsoft or Google. Zoorik never sees your password. A session ends after 30 minutes of inactivity, or after 12 hours.

$ zoorikctl cluster disconnect --kube-context <name>

• Add --dry-run to see everything it would remove first.
• Disconnect works even if the agent is down, and is safe to run again.
• It removes the agent, the webhook, the live-migration daemon, Coral’s roles, policies and CRDs, and Coral’s taints and annotations on nodes.
• It deletes the HPAs Coral created, hands back the HPAs it took over, and restores the VPAs it switched off.
• It offers to remove the cloud identity and role assignment it created.
• Running pods keep their current sizes until they restart.

• The node autoscaler set up during connect.
• Coral’s zoorik-base node class and zoorik-rb-… rebalancing pools.
• The CRIU files on nodes, and the folder /var/lib/zoorik/checkpoints, which can hold a checkpoint from an interrupted move. Delete it.
• The “Zoorik Node Removal v1” role definition, workload identity, the OIDC issuer and the Pod Identity Agent add-on.
• The cluster’s entry in the console, shown as “Not reporting”, and the data Zoorik has already received.