Skip to main content
The Ankra Agent is a lightweight service that runs inside your Kubernetes cluster, enabling real-time communication with the Ankra platform. It provides secure, bidirectional connectivity for resource browsing, deployments, and cluster management.
The agent requires cluster-admin permissions to manage all Kubernetes resources and deploy add-ons.

​
What the Agent Does

Real-time Resource Streaming

Browse Deployments, Pods, Services, and 20+ resource types with live updates.

Pod Log Streaming

View container logs in real-time directly from the Ankra dashboard.

Helm Management

Deploy, upgrade, and manage Helm releases across your cluster.

Add-on Deployment

Install stacks and add-ons with ArgoCD integration for GitOps.

​
Installation

When you import a cluster, Ankra generates a Helm install command with a unique token: 
helm upgrade --install ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --create-namespace \
  --set config.token="YOUR_UNIQUE_TOKEN"
The agent will connect to the platform and your cluster will appear online within seconds.

​
Verify Installation

Check the agent is running: 
kubectl get pods -n ankra
View agent logs: 
kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent -f

​
Configuration Reference

​
Required Settings

ParameterDescription
config.tokenAuthentication token (provided during cluster import)
config.ankra_urlPlatform URL (default: https://platform.ankra.app)

​
Using an Existing Secret

For production environments, store the token in a Kubernetes secret: 
kubectl create secret generic ankra-agent-secret \
  --namespace ankra \
  --from-literal=token=YOUR_UNIQUE_TOKEN
Then reference it in your Helm install: 
helm upgrade --install ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --set config.existing_secret_name=ankra-agent-secret \
  --set config.secret_key=token

​
Performance Tuning

For large clusters (1000+ resources), adjust these settings:
ParameterDefaultDescription
nats_worker_max_workers15Worker threads for command processing
resources.limits.memory200MiMemory limit
resources.requests.memory100MiMemory request
replica_count1Number of agent replicas
Example for large clusters: 
helm upgrade --install ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --set config.token="YOUR_TOKEN" \
  --set nats_worker_max_workers=25 \
  --set resources.limits.memory=512Mi \
  --set resources.requests.memory=256Mi

​
All Helm Values

ParameterDefaultDescription
config.ankra_urlhttps://platform.ankra.appPlatform API URL
config.token""Agent authentication token
config.existing_secret_name""Name of existing K8s secret
config.secret_key""Key in existing secret containing token
log_levelINFOLog level (DEBUG, INFO, WARNING, ERROR)
nats_worker_max_workers15NATS worker threads
replica_count1Number of agent pods
terminationGracePeriodSeconds600Graceful shutdown timeout
resources.limits.memory200MiMemory limit
resources.requests.memory100MiMemory request

​
Architecture

The agent uses a NATS-based architecture for real-time communication: 
┌─────────────────┐         ┌──────────────────┐
│  Ankra Portal   │◄───────►│  Ankra Platform  │
└─────────────────┘   HTTPS └────────┬─────────┘
                                     │
                                     │ NATS JetStream
                                     │
                              ┌──────▼─────────┐
                              │  Ankra Agent   │
                              │  (in-cluster)  │
                              └──────┬─────────┘
                                     │
                                     │ Kubernetes API
                                     │
                              ┌──────▼─────────┐
                              │   Your Cluster │
                              └────────────────┘
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
  • Health monitoring - Exposes /health and /ready endpoints on port 8080

​
Network Requirements

The agent requires outbound connectivity to:
EndpointPortPurpose
platform.ankra.app443API communication
connect.ngs.global4222NATS real-time streaming
No inbound ports need to be opened on your cluster.

​
Upgrading the Agent

​
From the Platform

Click Upgrade Agent in the cluster settings. The agent will self-upgrade using Helm.

​
Manually

helm upgrade ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --reuse-values
Check the current agent version: 
kubectl get deployment -n ankra ankra-agent -o jsonpath='{.spec.template.spec.containers[0].image}'

​
Troubleshooting

​
Agent Not Connecting

  1. Check agent pods are running: 
    kubectl get pods -n ankra
  2. View agent logs: 
    kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent --tail=100
  3. Verify network connectivity: 
    kubectl run --rm -it --restart=Never debug --image=curlimages/curl -- \
  curl -s https://platform.ankra.app/health
  4. Check the token is set: 
    kubectl get secret -n ankra ankra-agent -o jsonpath='{.data.token}' | base64 -d

​
Common Issues

IssueCauseSolution
Cluster shows OfflineAgent not running or network blockedCheck pods and firewall rules
Token invalidToken expired or revokedGo to Clusters → Your Cluster → Settings → Generate Command to get a new install command
Connection refusedOutbound network blockedAllow connections to platform.ankra.app:443
Resources not loadingAgent memory limits too lowIncrease resources.limits.memory

​
Health Checks

The agent exposes health endpoints: 
kubectl port-forward -n ankra svc/ankra-agent 8080:8080
curl http://localhost:8080/health
curl http://localhost:8080/ready

​
Uninstalling

To remove the agent from your cluster: 
helm uninstall ankra-agent -n ankra
kubectl delete namespace ankra
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 ArgoCD applications
  • Stream pod logs
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