Skip to main content
Ankra has to reach into your cluster to deploy Stacks, read resources and stream logs, but you should not have to open the cluster to the internet for that. The Ankra Agent solves this: it runs inside the cluster, opens an outbound connection to Ankra, and carries every request over it. How Ankra Works shows where the agent sits in the overall model. The agent ships as a single Go binary, installed with a Helm chart into the ankra namespace. Whether the platform upgrades a cluster’s agent for you depends on the auto-upgrade settings described in Upgrading the Agent.
The agent requires cluster-admin permissions to manage all Kubernetes resources and deploy add-ons.

What the Agent Does

  • Resource browsing - lists and watches Deployments, Pods, Services and other resource types for the portal, CLI and AI.
  • Pod logs - streams a container’s log when someone opens it in the portal or the CLI, or when Ankra AI reads it to answer a question. On a cluster with Ankra hosted logs turned on (off by default), the agent also sends the log lines of the cluster’s containers to Ankra, which keeps them for up to 7 days.
  • Platform metrics - sends node, namespace and workload usage, and request counts and response times from a Traefik ingress controller, to Ankra every 30 seconds for cluster metrics, unless the cluster opts out.
  • Deployments - installs and upgrades your Stacks’ add-ons and manifests with the native Helm engine (the default) or through ArgoCD. See Deployment Engines.
  • kubectl access - proxies authenticated kubectl requests to the cluster API server with no inbound ports. See Accessing Clusters with kubectl.
What leaves your cluster lists everything the agent sends and how long Ankra keeps it, and How to restrict it says how to turn each part off.

Installation

When you connect a cluster you run yourself, Ankra generates a Helm install command with a unique token (see Import a Cluster). It looks like this:
Copy the exact command from the Connect your cluster step rather than typing this one: it pins the agent version and carries your cluster’s token. The agent connects to the platform, and the page tells you once Ankra hears from it. Check now asks again straight away.

Verify Installation

Check the agent is running:
View agent logs:

Cluster States

What the agent reports and what Ankra knows about the cluster’s lifecycle show up in two places. The agent’s connection. A cluster’s overview and settings show whether its agent is reachable: While the cluster is starting or stopping, being deleted or archived, that state is shown in place of the connection, for example Stopping, Being deleted or Archived. The cluster list. Infrastructure → Clusters can be filtered by state: Online, Offline, Being created, Provider access needed, Provider connected, Kubernetes connected, Running, Stopped, Being deleted and Archived. While the agent is offline, the cluster’s workloads keep running, but Ankra cannot deploy to the cluster or show live resources and logs. Its configuration and history stay available. To bring it back, see Agent Not Connecting.

Configuration Reference

Required Settings

Using an Existing Secret

For production environments, store the token in a Kubernetes secret:
Then reference it in your Helm install:

Performance Tuning

For large clusters (1000+ resources), adjust these settings: Example for large clusters:

Public IP reporting

To have the agent report the cluster’s public egress IP to Ankra on check-in:
When enabled, the agent performs an outbound HTTP lookup (to public_ip.lookup_url, default https://api.ipify.org?format=json) and reports the result. Leave it disabled (the default) for air-gapped clusters or where egress IP lookups are undesirable.

All Helm Values

The complete value list - connection, workers, watch tuning, public IP reporting, image, security contexts, scheduling, and metrics - lives in the Agent Helm Values reference.
The agent runs as a non-root container by default (runAsNonRoot: true, UID/GID 1000, readOnlyRootFilesystem: true, all Linux capabilities dropped, seccompProfile: RuntimeDefault). Because the root filesystem is read-only, the chart mounts writable emptyDir volumes for /tmp, ~/.cache, and ~/.config via writable_volumes.enabled (default true). Don’t lower these security settings unless you are running a custom image.

Advanced tuning via extra_env

Less-common knobs are set as environment variables through extra_env:

Architecture

The agent uses a NATS-based architecture for real-time communication: Key features:
  • Outbound connections only - The agent initiates all connections, no inbound ports required
  • Real-time streaming - Resource data streams efficiently using pagination
  • Automatic reconnection - Handles network interruptions gracefully
  • kubectl proxy - Forwards authenticated kubectl requests (including watch, logs -f, and exec) from the platform to the cluster API server, so you can reach private clusters without inbound access. See Accessing Clusters with kubectl.
  • Health monitoring - Exposes /livez and /readyz endpoints on port 8080

Network Requirements

The agent requires outbound connectivity to: No inbound ports need to be opened on your cluster.

Upgrading the Agent

When automatic upgrades are on, the platform rolls clusters forward to the latest published agent release, a few clusters at a time. You can still trigger an upgrade yourself at any time. Upgrading the agent does not change your apps.
  • For the organisation: the switch is under Build & delivery → Builds and clusters, in the Cluster agents section. New organisations have it on by default. With it off, each cluster shows when a new agent is out, and you upgrade it from there.
  • For one cluster: Infrastructure → Clusters → <your cluster> → Settings → Agent shows the agent’s Connection, Version, Last check-in and Automatic upgrades. Turn automatic upgrades off keeps this cluster’s agent on its version whatever the organisation setting says; Turn automatic upgrades on reverses it.
  • Every change to either switch is recorded in the audit log (as set_agent_auto_upgrade for a cluster, on update_organisation for the organisation) with who made it, the setting it replaced and, when one was given, the reason (ankra cluster agent auto-upgrade disable --reason "...", or reason on the MCP tool set_cluster_agent_auto_upgrade). Changes to the agent’s sizing and pipeline settings are recorded the same way.

From the Platform

On Infrastructure → Clusters → <your cluster> → Settings → Agent, Upgrade agent opens Upgrade the agent on <cluster>; confirm with Upgrade agent. The button then reads Upgrade requested, and the agent upgrades itself with Helm.

From the CLI

An upgrade you trigger never moves an agent backwards on its own: without --version an agent already on a newer release stays on it. A --version older than the running release is refused unless --allow-downgrade is also given, and a release that is neither published nor the one the agent runs is refused too; both refusals say why and change nothing. The MCP tool upgrade_cluster_agent takes the same version and allow_downgrade. See ankra cluster agent upgrade.

Manually

Check the current agent version:

Troubleshooting

Agent Not Connecting

  1. Check agent pods are running:
  2. View agent logs:
  3. Verify network connectivity:
  4. Check the token is set:
    The chart stores the token in the Secret ankra-identity-secret under the key TOKEN. With config.existing_secret_name, read that Secret and the key you set as config.secret_key instead.

Common Issues

Health Checks

The agent exposes health endpoints:

Uninstalling

To remove the agent from your cluster:
Uninstalling the agent will disconnect your cluster from Ankra. You’ll need to re-import it to reconnect.

Security

RBAC Requirements

The agent requires cluster-admin permissions to:
  • Browse all Kubernetes resources
  • Deploy Helm charts and manifests
  • Manage add-ons via the native Helm engine or ArgoCD
  • Stream pod logs and proxy authenticated kubectl requests
The Helm chart creates a ClusterRoleBinding with the necessary permissions.

Token Security

  • Tokens are unique per cluster
  • Tokens can be revoked by deleting the cluster from Ankra
  • Store tokens in Kubernetes secrets (not in Helm values) for production