Kubernetes (kubectl + kubeconfig)

Paste a view-only ServiceAccount kubeconfig and the agent runs kubectl reads against the cluster; which verbs and flags pass, what Connect and verify runs, and the save-time checks.

How-to · Updated 2026-10-27 · Describes release 0.1.164

Overview

A kubectl connection gives the agents direct, read-only cluster access from a pasted kubeconfig, with no MCP server in between. The Incident agent reads pods, events, rollouts and logs through it (Kubernetes is one of the five categories that agent needs), the Compliance agent reads cluster state for its controls, and the estate x-ray harvests the inventory from it. A second, write-role kubectl connection is how an approved deployment restart runs.

The binary runs on the platform host, or inside a private-network agent for a cluster whose API is private; in that case the agent's image must include kubectl.

Setup

Before you start

• The datasources.manage permission; the built-in owner and operator roles carry it.
• A kubeconfig for a view-only ServiceAccount that may also get and list nodes (Installation).
• The API server reachable from the platform, or a private-network agent in the cluster's network.

Installation

Create a dedicated ServiceAccount bound to the built-in view role in the namespaces the agent may read, plus get and list on nodes, which the connection check needs; the default view role alone does not allow the node probe. Export a kubeconfig whose current context names that account, the cluster's CA embedded as certificate-authority-data and, when the account is namespace-bound, the namespace. Connect Kubernetes has a copy-and-run command that does exactly this for one namespace and prints aiops-readonly.kubeconfig. Exclude Secrets, pods/exec and every write from the role; the platform refuses writes anyway, but RBAC is the real boundary. A token from kubectl create token expires; decide how it is renewed.

Configuration

1. Open Settings · Data in → Data sources and select Connect datasource.
2. Under Type, choose Kubernetes (kubectl + kubeconfig). Enter a Connection name; the connected list shows it, and per-connection agent tools are named after it.
3. Fill the fields:

4. Optionally, open Optional · describe this environment and fill What should AIOps know about it? with the cluster, the namespaces and the critical services.
5. Under Use this connection for, choose Investigate only and select Connect and verify.

The same connection through the API (POST /api/aiops/{tenant_id}/datasources, requires datasources.manage; the kubeconfig goes in secret_values, and one posted in config is moved there):

{
  "type_key": "kubectl",
  "name": "prod-eks",
  "description": "Production cluster; checkout and payments run in the payments namespace.",
  "config": {
    "namespaces": "payments, checkout"
  },
  "secret_values": {
    "kubeconfig": "apiVersion: v1\nkind: Config\nclusters:\n- name: estate\n  cluster:\n    server: https://<api-server>\n    certificate-authority-data: <base64>\ncontexts:\n- name: estate\n  context:\n    cluster: estate\n    user: aiops-reader\n    namespace: payments\ncurrent-context: estate\nusers:\n- name: aiops-reader\n  user:\n    token: <service-account token>\n"
  },
  "role": "read",
  "enabled": true
}

The save validates the paste: 'kubeconfig' is not valid YAML (…) — paste the full file preserving line breaks or 'kubeconfig' does not parse as a YAML mapping — line breaks were probably lost in the paste is a 400 at save time, not a failure mid-investigation. The accepted kubeconfig forms are a user with a static token (a ServiceAccount token) or with client-certificate-data and client-key-data, and a cluster with certificate-authority-data; everything the file needs is inside it. A kubeconfig whose user runs a credential plugin (exec, such as aws eks get-token or kubelogin, or the older auth-provider), or that names a file on the platform host (tokenFile, client-certificate, client-key, certificate-authority as a path), is refused the same way with This kubeconfig runs a credential plugin (users[].user.exec or auth-provider) or names a file on the platform host (tokenFile, client-certificate, client-key, certificate-authority); the platform does neither. Use a kubeconfig with a static token or a service-account token and embedded certificate data (certificate-authority-data, client-*-data). The platform image ships no such plugin, kubectl would otherwise read the named file from the platform host (a tokenFile is sent to the kubeconfig's server as the bearer token), and a connection saved before this check gets the same message from every tool call and Test instead of running kubectl. The pasted kubeconfig is also the only identity kubectl can use: the platform strips the pod's in-cluster API discovery from every connector process, so a kubeconfig that resolves to no server ({}, a file without current-context) fails against localhost:8080 instead of answering with the platform's own service account, and a connection saved with a blank kubeconfig answers the connection's 'kubeconfig' is blank — paste it and save the connection before use instead of running kubectl.

Validation

Connect and verify, and Test on the row later, looks for kubectl on the host's PATH, tries kubectl --version, then runs kubectl get nodes --request-timeout=5s -o name with the kubeconfig written to a private file and passed through KUBECONFIG. You should see a dialog titled <connection name> is connected with Connected — verified from the control plane, and later in the row's Last test ok · binary found: /usr/local/bin/kubectl — … — 'kubectl get nodes --request-timeout=5s -o name' ok (node/<name>), the last line of the real output. A kubeconfig that does not parse, an API server that does not answer and a ServiceAccount without node read all fail here. When a private-network agent serves the workspace, the platform does not run the command itself: the row shows the check as queued, the agent runs it, and the result reads Connected — verified by your private-network agent.

If something fails

The dialog shows Needs a fix, what to fix and the check's own detail; the row is saved either way. Select Edit, correct the field the detail names and save again, or select Retry once a cause outside the form (network, vendor-side permission) is fixed. Every verdict this connector produces, and what to do about it, is in Troubleshooting below.

Data collected

Tools the agent gets

• <name>_exec — runs kubectl with the argument vector the agent passes; a leading kubectl in the vector is dropped. The kubeconfig's current context is preconfigured, and the tool description tells the agent not to pass --context or --kubeconfig unless the connection notes name a context. Output is the merged stdout and stderr, exit code <n> first on a failure, capped at 20,000 characters; a command is killed after 60 seconds (timed out after 60s), and a missing binary at run time reads cannot run 'kubectl': ….

A kubectl connection registers no HTTP tool. The estate x-ray uses the same tool under its own, stricter read set, which does not include logs or events.

Read surface

An investigation runs a kubectl call only when the platform's own kubectl adapter verifies it as a read, independently of the connection's verb list. What passes: the verbs get, describe, top, explain, api-resources, api-versions, cluster-info (not cluster-info dump), version, logs, events, help and auth can-i, optionally preceded by the global flags --context, --namespace or -n, --request-timeout and --v with their values. What is refused, never offered for approval: every other verb (apply, delete, scale, rollout restart, exec, cp, patch, edit), diff although the catalog lists it among the read verbs, any other leading flag, and anywhere in the vector --raw, --subresource, --server or -s, --kubeconfig, --token, --as, --client-*, --certificate-*, --insecure-*, --username and --password, so only the saved credential and the saved cluster are ever used. The refusal reads Investigation connections are read-only. This operation was not executed; prepare an incident change using a write connection and obtain approval.

The catalog's own list — get, describe, top, explain, api-resources, api-versions, cluster-info, version, logs, events, diff — is the approval gate's read set; the verified adapter above is the floor underneath it. The full rule table is under The read/write gate in detail in Connections and remediation access.

Inventory and namespaces

The estate inventory first lists each kind cluster-wide. When that is Forbidden, it reads kubectl get <kind> -n <namespace> for every namespace in Namespaces, else the current context's namespace, and its notes say namespace-scoped read: N namespace(s) from …. Nodes or namespaces that stay unreadable leave the pods without a host and the namespace-selector NetworkPolicies flagged, and a blast radius touching them is reported as estimated with that coverage gap.

Approved fixes

A deployment restart runs through a second kubectl connection saved as Approved changes only (separate credential) with Allow use for approved plans ticked, on a ServiceAccount scoped to the namespace and the verbs the fix needs. The namespace in that kubeconfig's context is the scope a restart may target; a context without one confirms none. How approvals and tiers apply is in Set up write connections.

Troubleshooting

The generic verdict strings are explained in Test a connection and read the failure. Every connection status word is in the status and error reference.

Next steps

• Select Discover this connection in the success dialog to find the services and dependencies behind it: Launch a scan.
• See what the inventory reads per namespace: Inventory and namespaces.
• Run approved fixes through a separate write connection: Approved fixes.
• See what else each agent needs in Choose your connection.