> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ankra Agent

> Learn how the Ankra Agent connects your Kubernetes cluster to the platform.

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 ships as a single, statically compiled **Go binary** on the **2.x version track** (`2.0.x`). It is a drop-in replacement for earlier agents - the same Helm chart, values, install command, and behaviour - with a smaller memory and CPU footprint and faster startup. Existing clusters are upgraded automatically by the platform; there is nothing to change in your install command.

<Note>
  The agent requires **cluster-admin** permissions to manage all Kubernetes resources and deploy add-ons.
</Note>

***

## What the Agent Does

<CardGroup cols={2}>
  <Card title="Real-time Resource Streaming" icon="satellite-dish">
    Browse Deployments, Pods, Services, and 20+ resource types with live updates.
  </Card>

  <Card title="Pod Log Streaming" icon="terminal">
    View container logs in real-time directly from the Ankra dashboard.
  </Card>

  <Card title="Helm Management" icon="box">
    Deploy, upgrade, and manage Helm releases across your cluster, including history and rollback.
  </Card>

  <Card title="Add-on Deployment" icon="layer-group">
    Install stacks and add-ons using the native Helm engine (default) or ArgoCD. See [Deployment Engines](/concepts/deployment-engines).
  </Card>

  <Card title="kubectl Access" icon="terminal">
    Proxy authenticated `kubectl` requests to the cluster API server - no inbound ports. See [Accessing Clusters with kubectl](/guides/kubeconfig).
  </Card>

  <Card title="Fleet Map Reporting" icon="location-dot">
    Optionally report the cluster's public egress IP so it appears on the [Dashboard](/platform/dashboard) world map.
  </Card>
</CardGroup>

***

## Installation

When you import a cluster, Ankra generates a Helm install command with a unique token:

```bash theme={null}
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:

```bash theme={null}
kubectl get pods -n ankra
```

View agent logs:

```bash theme={null}
kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent -f
```

***

## Configuration Reference

### Required Settings

| Parameter          | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `config.token`     | Authentication token (provided during cluster import) |
| `config.ankra_url` | Platform URL (default: `https://platform.ankra.app`)  |

### Using an Existing Secret

For production environments, store the token in a Kubernetes secret:

```bash theme={null}
kubectl create secret generic ankra-agent-secret \
  --namespace ankra \
  --from-literal=token=YOUR_UNIQUE_TOKEN
```

Then reference it in your Helm install:

```bash theme={null}
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:

| Parameter                   | Default | Description                                                   |
| --------------------------- | ------- | ------------------------------------------------------------- |
| `nats_worker_max_workers`   | `15`    | Worker threads for command processing                         |
| `read_worker_count`         | `5`     | Concurrent worker slots for read jobs                         |
| `write_worker_count`        | `5`     | Concurrent worker slots for write jobs (create/update/delete) |
| `resources.limits.memory`   | `512Mi` | Memory limit                                                  |
| `resources.requests.memory` | `256Mi` | Memory request                                                |
| `replica_count`             | `1`     | Number of agent replicas                                      |

Example for large clusters:

```bash theme={null}
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=1Gi \
  --set resources.requests.memory=512Mi
```

### Fleet world map (public IP reporting)

To place an imported cluster on the [Dashboard](/platform/dashboard) world map when it has no recognisable cloud region, let the agent report its public egress IP on check-in:

```bash theme={null}
helm upgrade --install ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --set config.token="YOUR_TOKEN" \
  --set public_ip.reporting_enabled=true
```

When enabled, the agent performs an outbound HTTP lookup (to `public_ip.lookup_url`, default `https://api.ipify.org`) 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](/reference/agent-helm-values).

<Note>
  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.
</Note>

### Advanced tuning via `extra_env`

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

| Env var                                       | Default | Description                                                                     |
| --------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `KUBERNETES_HTTP2_ENABLED`                    | `false` | Enable HTTP/2 to the API server (only if the path supports it cleanly)          |
| `KUBERNETES_REQUEST_MAX_ATTEMPTS`             | `3`     | List/get retry attempts on connection-terminated errors                         |
| `KUBE_PROXY_UNARY_CONCURRENCY`                | `64`    | Max concurrent unary requests through the kubectl proxy                         |
| `KUBE_PROXY_STREAM_CONCURRENCY`               | `128`   | Max concurrent streaming connections (watch/logs/exec) through the proxy        |
| `DYNAMIC_API_DISCOVERY_ENABLED`               | `false` | Discover and watch additional API groups dynamically                            |
| `RECONCILE_AUTO_HEAL_ENABLED`                 | `true`  | Auto-heal native-engine releases stuck mid-operation                            |
| `FORWARD_SERVICE_REQUEST_MAX_TIMEOUT_SECONDS` | `120`   | Upper bound for platform-requested forwarded-request timeouts (e.g. Prometheus) |

```yaml theme={null}
extra_env:
  - name: KUBERNETES_REQUEST_MAX_ATTEMPTS
    value: "5"
```

***

## Architecture

The agent uses a NATS-based architecture for real-time communication:

```mermaid theme={null}
flowchart TB
    Portal[Ankra Portal] <-->|HTTPS| Platform[Ankra Platform]
    Platform <-->|NATS JetStream| Agent[Ankra Agent]
    Agent <-->|Kubernetes API| Cluster[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
* **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](/guides/kubeconfig).
* **Health monitoring** - Exposes `/livez` and `/readyz` endpoints on port 8080

***

## Network Requirements

The agent requires outbound connectivity to:

| Endpoint             | Port | Purpose                  |
| -------------------- | ---- | ------------------------ |
| `platform.ankra.app` | 443  | API communication        |
| `connect.ngs.global` | 4222 | NATS real-time streaming |

No inbound ports need to be opened on your cluster.

***

## Upgrading the Agent

New agent releases are published on the `2.0.x` version track. The platform rolls the fleet forward automatically to the latest published version, a few clusters at a time, so most clusters stay current without any action. You can still trigger an upgrade yourself at any time.

### From the Platform

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

### Manually

```bash theme={null}
helm upgrade ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --reuse-values
```

Check the current agent version:

```bash theme={null}
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:**
   ```bash theme={null}
   kubectl get pods -n ankra
   ```

2. **View agent logs:**
   ```bash theme={null}
   kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent --tail=100
   ```

3. **Verify network connectivity:**
   ```bash theme={null}
   kubectl run --rm -it --restart=Never debug --image=curlimages/curl -- \
     curl -s https://platform.ankra.app/health
   ```

4. **Check the token is set:**
   ```bash theme={null}
   kubectl get secret -n ankra ankra-agent -o jsonpath='{.data.token}' | base64 -d
   ```

### Common Issues

| Issue                 | Cause                                | Solution                                                                                 |
| --------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
| Cluster shows Offline | Agent not running or network blocked | Check pods and firewall rules                                                            |
| Token invalid         | Token expired or revoked             | Go to Clusters → Your Cluster → Settings → Generate Command to get a new install command |
| Connection refused    | Outbound network blocked             | Allow connections to `platform.ankra.app:443`                                            |
| Resources not loading | Agent memory limits too low          | Increase `resources.limits.memory`                                                       |

### Health Checks

The agent exposes health endpoints:

```bash theme={null}
kubectl port-forward -n ankra svc/ankra-agent 8080:8080
curl http://localhost:8080/livez
curl http://localhost:8080/readyz
```

***

## Uninstalling

To remove the agent from your cluster:

```bash theme={null}
helm uninstall ankra-agent -n ankra
kubectl delete namespace ankra
```

<Warning>
  Uninstalling the agent will disconnect your cluster from Ankra. You'll need to re-import it to reconnect.
</Warning>

***

## 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