> ## 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.
# Cluster Investigator
> Combines Kubernetes RCA, Grafana telemetry and GPU diagnostics in one in-cluster agent, deployed one per cluster.
Deploy this agent when one cluster needs an investigator that can read the cluster itself, the
telemetry around it, and — where you run them — the GPUs underneath it. It is the combined
alternative to running a cluster investigator and a telemetry investigator side by side. This page
covers what it reaches, the access it needs, and where it stops.
## What it does
You describe what is wrong and it investigates across all three signal sources at once: reading
cluster state through read-only `kubectl`, pulling the metrics, logs and traces around the incident
from Grafana, and checking GPU health where the workload depends on it. It reconstructs the change
timeline and returns a structured root-cause analysis.
The point of combining them is correlation that neither half can do alone — a pod restarting because
of a GPU fault looks like an ordinary crash loop until something reads both.
## What it reads
All of it read-only, apart from the in-pod diagnostics noted below.
| Source | What it uses it for |
| ----------------------- | ---------------------------------------------------------------------- |
| Kubernetes | Cluster state, dependencies, events, and the change timeline |
| Prometheus, Loki, Tempo | Metrics, logs and traces around the incident window |
| GPU health signals | XID and SXid errors, DCGM metrics, and inference-engine crash patterns |
It carries the same domain knowledge as [Kubernetes
RCA](/manage-your-agents/build/catalog/kubernetes-rca) — twenty-three workload-specific methods —
plus five GPU-specific ones.
## 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, one instance per cluster | [Deploy an agent](/manage-your-agents/build/deploy-an-agent) |
| Grafana access | Optional — see below | [Built-in integrations](/manage-your-agents/build/built-in-integrations) |
| Cluster RBAC | Granted by the rendered install, including in-pod diagnostics | — |
The Grafana connection is optional because the agent can instead reach your own in-cluster MCP
server, or run its own bundled Grafana tooling. Add a connection only to use the built-in path.
Without any of the three, it still investigates the cluster — it simply has no telemetry to
correlate against.
The install grants the same cluster access as Kubernetes RCA: Kubernetes' aggregated `view` role, a
supplemental role for the cluster-scoped reads it omits, and `pods/exec` for the workload methods
that diagnose from inside the pod. Exec is a separate value, so you can narrow it to named
namespaces or remove it and let those methods fall back to resource state.
## Ask it for
In chat, or as a run's prompt:
```text theme={null}
The inference-gateway deployment in namespace ml-serving has been restarting since
06:00 UTC. Check the pods, the GPU health on the nodes they land on, and the Grafana
metrics for that window. Tell me whether this is the workload or the hardware.
```
## Defaults and limits
| | |
| ----------- | --------------------------------------- |
| Catalog ID | `cluster-investigator` |
| Model | `claude-sonnet-4-6` |
| Time budget | 600 seconds, adjustable 60–1800 per run |
| Deployment | Self-hosted only |
| Chat | Yes |
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 step targeting it has already established which
cluster the problem is in. Because it covers three signal sources, it often replaces two steps that
would otherwise run in parallel and need synthesizing afterwards.
See [Orchestration](/manage-your-agents/run/orchestration) for how a step delivers work to it.
## What it will not do
It changes nothing in the cluster or in Grafana. Its non-read grant is confined to a fixed list of
read-only in-pod diagnostics, and everything else is refused.
It sees exactly one cluster. Deploying one instance and expecting it to answer for a fleet is the
mistake worth avoiding — run one per cluster, and name each after the cluster it watches.
## Next steps
The cluster half alone, with no external data sources.
The telemetry half alone, across clusters.
Install a self-hosted worker into your cluster.
Every catalog agent, side by side.
## Related topics
- [Grafana Investigator](/manage-your-agents/build/catalog/grafana-investigator.md)
- [Azure Investigator](/manage-your-agents/build/catalog/azure-investigator.md)
- [Agent catalog](/manage-your-agents/build/catalog/overview.md)
- [Kubernetes RCA](/manage-your-agents/build/catalog/kubernetes-rca.md)
- [Use specialized agents](/manage-your-agents/build/use-specialized-agents.md)