> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kubernetes RCA
> Root-causes a single Kubernetes resource from inside its own cluster, using read-only kubectl and nothing else.
Deploy this agent when you want root-cause analysis for a Kubernetes resource without the
investigation leaving the cluster. It runs in-cluster, reads through `kubectl` only, and reaches no
Komodor backend and no external data source. This page covers the one scope decision that matters
before you install it, the access it needs, and where it stops.
## What it does
You name a resource — a kind and a name — and it investigates that resource: reconstructing what
changed around it, reading the state of its dependencies, and working through a domain-specific
method for whatever it is. It is built from Klaudia's root-cause knowledge, which is why it knows
how to diagnose a Kafka consumer group or a stuck Istio sidecar rather than only reading events.
It returns a structured root-cause analysis for that one resource.
This agent investigates **only the cluster it is deployed in**. One instance does not answer for a
fleet, and that is the mistake worth avoiding before you install rather than after. For
multi-cluster work, use [Klaudia
Investigator](/manage-your-agents/build/catalog/klaudia-investigator) instead.
The wizard states this on its first step and holds Next until you confirm it, and it recommends
putting the cluster name in the agent's name for exactly this reason.
## What it reads
Read-only `kubectl` against the cluster it runs in. There is no connection to bind, because the
ServiceAccount's own permissions are simultaneously its only data source and its only security
boundary.
| Source | What it uses it for |
| ------------------------- | -------------------------------------------------------------------- |
| Namespaced resources | The resource under investigation and everything it depends on |
| Cluster-scoped reads | Nodes, persistent volumes, storage classes, API services and metrics |
| Events and change history | Reconstructing what changed before the failure |
| In-pod diagnostics | State that exists nowhere else, for a short list of workload types |
## Before you deploy
| Requirement | Detail | Where to set it up |
| ------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| Model access | The managed model gateway, or your own Claude API key | [Credentials & secrets](/manage-your-agents/build/credentials-secrets) |
| A cluster to run in | Self-hosted only — there is no Komodor cloud option | [Deploy an agent](/manage-your-agents/build/deploy-an-agent) |
| Cluster RBAC | Granted by the rendered install; see below | — |
The self-hosted install renders a values file that binds the agent's ServiceAccount to Kubernetes'
own aggregated `view` role, plus a supplemental role for the cluster-scoped reads `view` omits.
Leaning on the built-in role means custom resources are covered as they are installed, rather than
by a list that goes stale.
### The one grant that is not read-only
`pods/exec` is granted cluster-wide, because several domain methods diagnose from inside the pod —
that state exists nowhere else, and at install time nobody knows which namespace an incident will
land in.
It is a separate value from the read access, so you can narrow or remove it:
| Value | Effect |
| ----------------------- | ------------------------------------------------------------------ |
| `rbac.exec.namespaces` | Restrict in-pod diagnostics to named namespaces |
| Removing the exec block | Those methods fall back to resource state; the rest are unaffected |
What may actually run through that grant is decided by the agent itself, not only by RBAC. It admits
a short list of read-only diagnostics and refuses everything else, interactive sessions included.
No database client is on that list, so a Postgres incident that turns on a grant or a row-security
policy is out of reach — and the agent names that as a blind spot rather than approximating.
The `view` role excludes Secrets, so Helm release history is unavailable and the change-timeline
method falls back to its other sources. Two grants are deliberately off by default and need an
edit to the values file: reads on custom resource groups that do not aggregate to `view`, and
cluster-wide Secret reads.
## Ask it for
This agent takes a resource, not a question. A run's input names what to investigate:
| Field | What it is |
| ---------------- | ------------------------------------------------------------- |
| `kind` | The resource kind — `Deployment`, `StatefulSet`, `Pod`, `Job` |
| `name` | The resource name |
| `namespace` | Its namespace; omit for cluster-scoped kinds |
| `budget_seconds` | A shorter or longer wall-clock budget for this run |
```json theme={null}
{
"kind": "StatefulSet",
"name": "kafka-broker",
"namespace": "streaming"
}
```
## Defaults and limits
| | |
| ----------- | ----------------------------------------------------- |
| Catalog ID | `kubernetes-rca` |
| Model | `claude-sonnet-5` |
| Time budget | 600 seconds, adjustable 60–1800 per run |
| Deployment | Self-hosted only |
| Chat | No — it takes a resource envelope, not a conversation |
The time budget degrades rather than fails. At 70% the agent is nudged to converge; at 100% further
tool calls are refused and it reports what it has.
## In a workflow
It is a specialist bound to one cluster, so a workflow step that targets it has already decided
which cluster the problem is in. Where a fleet-wide investigation is the starting point, an
orchestrator reaches for a multi-cluster investigator first and delegates here once the cluster is
known.
See [Orchestration](/manage-your-agents/run/orchestration) for how a step delivers work to it.
## What it will not do
It changes nothing. Its read access is the whole of its reach, and the one non-read grant is
confined to a fixed list of diagnostics by the agent's own classifier.
It also sees exactly one cluster and no external context. It has no Komodor backend, no metrics
vendor and no cloud provider API — so a cause that lives in any of those is outside what it can
observe, and it says so rather than inferring.
## Next steps
The same cluster knowledge, plus Grafana telemetry and GPU health.
Kubernetes investigation that spans clusters.
Install a self-hosted worker into your cluster.
Every catalog agent, side by side.
## Related topics
- [Cluster Investigator](/manage-your-agents/build/catalog/cluster-investigator.md)
- [Klaudia Investigator](/manage-your-agents/build/catalog/klaudia-investigator.md)
- [Agent catalog](/manage-your-agents/build/catalog/overview.md)
- [Marketplace](/manage-your-agents/build/marketplace.md)
- [Kubernetes Cost](/modules-and-workflows/cost-optimization/k8s-cost.md)