Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt

Use this file to discover all available pages before exploring further.

Every workload cluster that AcornOps observes runs a k8s agent. The agent opens an outbound WebSocket to the control plane, reports cluster state, and executes allowed Kubernetes tools during troubleshooting runs.

​
Registration flow

  1. Open the workspace in the management console.
  2. Register a new cluster.
  3. Copy the install instructions returned by the control plane.
  4. Run the generated Helm command against the workload cluster.
  5. Confirm the cluster shows as connected.
The registration response includes { cluster, agentKey, installInstructions }. Treat installInstructions.command as authoritative.

​
Agent connection

By default, the agent derives its WebSocket URL from the platform URL: 
wss://acornops.dev/api/v1/agent/connect
The agent authenticates with the issued agent key. Store the key in a Kubernetes Secret for long-running installs, or use the generated command for first-time setup.

​
Namespace scope

Use namespace include and exclude lists to limit what the agent observes and what builtin tools may touch.
SettingBehavior
Include listWhen non-empty, the agent watches only listed namespaces.
Exclude listSkips listed namespaces after include filtering.
Empty include and exclude listsWatches all namespaces allowed by RBAC.
Control-plane cluster updates persist namespace scope. If the connected agent supports dynamic scope updates, the control plane pushes the change over the existing WebSocket. Otherwise, the agent receives the persisted scope on the next reconnect.

​
RBAC scope

The agent chart can create cluster-scoped RBAC or namespace-scoped RBAC. Use cluster scope when AcornOps should observe the whole workload cluster. Use namespace scope when you want to constrain access to a known set of namespaces. Write-capable tools require explicit configuration:
  • the chart must grant mutation RBAC,
  • the agent must advertise write support,
  • the workspace role must allow read-write runs,
  • the run must be requested with read-write tool access.
Read-only runs cannot execute write tools even when the agent and RBAC support them.

​
Builtin tools

The current builtin Kubernetes tool set includes:
  • list_resources
  • get_resource
  • get_resource_logs
  • restart_workload
  • scale_workload
  • simulate_patch
  • apply_remediation
The agent owns builtin tool schemas and runtime behavior. The control plane owns registration, filtering, and how tools are exposed to the management console and LLM gateway.

​
High availability

The agent supports active-passive high availability. If you run more than one replica, enable Kubernetes Lease leader election: 
replicaCount: 2
leaderElection:
  enabled: true
Only the elected replica connects to the control plane. Other replicas wait and take over when the leader stops renewing its lease.

​
Verification

After installation, check:
  • the pod is running in the chosen namespace,
  • the agent logs show a successful handshake,
  • the management console shows the cluster as connected,
  • snapshots include resources and events,
  • metrics appear when the workload cluster has the metrics API available,
  • pod log reads work for roles with log permissions.
If the cluster stays disconnected, verify the platform URL, WebSocket route, agent key, outbound network access, and namespace/RBAC settings.