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

# Connect a Kubernetes cluster

> Register a Kubernetes target, install AgentK, and verify its connection

Every Kubernetes cluster that AcornOps observes runs AgentK. The connector 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 Kubernetes cluster.
5. Confirm the cluster shows as connected.

The registration response includes `{ cluster, agentKey, installInstructions }`. Treat `installInstructions.command` as authoritative.

## Namespace scope

Use namespace include and exclude lists to limit what the agent observes and what builtin tools may touch.

| Setting                         | Behavior                                                                   |
| ------------------------------- | -------------------------------------------------------------------------- |
| Include list                    | When non-empty, the agent watches only listed namespaces.                  |
| Exclude list                    | Skips listed namespaces after include filtering.                           |
| Empty include and exclude lists | Watches all namespaces allowed by RBAC except default platform exclusions. |

`kube-node-lease` and `kube-public` are excluded by default. 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.

In the management console, namespace scope is edited from Cluster Settings.

Automatic investigations have a separate namespace eligibility policy. That
policy can narrow which observed issues start an investigation, but it cannot
expand AgentK collection, RBAC, or tool access. See
[Configure automatic investigations](/use/automatic-investigations#limit-kubernetes-issue-eligibility).

## RBAC scope

The agent chart can create cluster-scoped RBAC or namespace-scoped RBAC.

Use cluster scope when AcornOps should observe the whole Kubernetes 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,
* `ACORNOPS_AGENT_WRITE_ENABLED` must be `true`,
* 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.

## Write confirmation policy

Each cluster has an effective write confirmation policy:

* `deployment_default`: inherits `ASSISTANT_WRITE_CONFIRMATION_REQUIRED`.
* `cluster_override`: uses the cluster's explicit override.

In the management console, this policy is managed from Cluster Settings alongside namespace scope.

When confirmations are required, the run pauses before each write-capable tool call and waits for an authorized user to approve or reject the pending write. Approval executes that one queued write once; rejection and timeout do not call the AgentK.

This approval resource is channel-agnostic. The management console renders it in chat, and bot adapters can render the same approval payload and call the same decision endpoint, as long as the click is attributable to a real AcornOps user with read-write run permission.

Cluster troubleshooting conversations are owner-write and viewer-read. The creator can send follow-ups while they still have run permissions. Other workspace users with cluster read access can open the conversation, read the persisted messages, and watch active run events live, but they cannot type into that conversation. Starting a separate conversation after recent cluster chat activity shows an inline warning, with stronger copy when the recent activity used write-capable tools.

## Builtin tools

The current builtin Kubernetes tool set includes:

* `list_resources`
* `get_resource`
* `get_resource_logs`
* `restart_workload`
* `scale_workload`
* `patch_resource`

The connected agent advertises the available builtin tools. AcornOps shows those tools in the target tool catalog and filters access based on workspace role, target policy, and run mode.

See [MCP and tools](/use/tools-and-mcp) for remote MCP server setup, public header policy, and tool enablement behavior.

## High availability

The agent supports active-passive high availability. If you run more than one replica, enable Kubernetes Lease leader election:

```yaml theme={null}
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.

## Private platform CA

When the AcornOps WebSocket certificate uses an organization-private CA, add that public CA bundle to AgentK without disabling TLS verification.

Add the bundle source to the same values file that you use for the AgentK release. For a local PEM file, add
`--set-file config.tls.additionalCaBundle.inlinePem=/path/to/organization-ca.pem` to your existing
`helm upgrade --install` command. Keep the rest of that command's release values unchanged.

You can instead reference one existing ConfigMap or Secret in the AgentK release namespace through `config.tls.additionalCaBundle.configMapKeyRef` or `secretKeyRef`. The sources are mutually exclusive. A missing resource or key prevents the pod from starting.

AgentK extends normal public CA trust and keeps certificate and hostname verification enabled. Existing ConfigMap or Secret content changes require a pod restart. Rotate private roots with an old/new overlap.

## Structured write safeguards

`patch_resource` accepts guarded semantic image, label, annotation, and explicitly enabled Service selector changes; it does not expose an arbitrary patch document or shell.

The local default permits Deployment, StatefulSet, and DaemonSet patching. CronJob, Service, and Ingress kinds require explicit `patchPolicy.kinds` configuration and matching RBAC. Service selector changes require both `patchPolicy.allowServiceSelectorChanges=true` and caller confirmation.

Scale-to-zero is disabled unless both the operator and caller opt in. Mutation receipts are minimal, and an uncertain write outcome must be inspected before any retry.

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