Kubesense Infra

KubeSense Infrastructure & Inventory

Telemetry tells you a service is unhealthy. These tools tell you what exists, what is failing at the Kubernetes layer, and what changed — the context that turns a symptom into a cause.

Requires the KubeSense MCP server. See kubesense-mcp for connection and auth.

Routing — Read This First

Discovery order. list-clusters → list-workloads / list-pods → get-*-detail. Names flow forward: never type a cluster, namespace, workload, or pod name you have not read out of a previous call.

Tools

Every tool defaults to the last 1 hour and all accessible clusters. Pass from_time/to_time (RFC3339) to widen; pass clusters to narrow.

list-clusters

Call this first when you need a cluster name. It is the only discovery for the clusters filter that every other tool accepts.

{ "search": "prod" }

Returns TSV: name, source, env_type, updated_at.

Nodes

{ "clusters": ["prod-us"], "sort_by": "memory_usage_precent", "sort_direction": "DESC" }

[!WARNING] sort_by for nodes is spelled _precent, not _percent — the accepted values are memory_usage_precent, disk_usage_precent, cpu_usage_precent. The output columns use the correct spelling (memory_usage_percent). Passing _percent to sort_by does not sort.

Output: name, cluster, ready, running_pods, cpu_usage_percent, memory_usage_percent, disk_usage_percent, kubelet_version, instance_type, uid, creation_timestamp.

get-node-detail takes name (required) and optional clusters to disambiguate a name present in several clusters. It returns conditions, addresses, labels, taints, and capacity/usage as a record with ## conditions / ## addresses sub-tables.

Pods

{ "namespace": "production", "status": "Pending", "sort_by": "memory_usage", "sort_direction": "DESC" }

• status filters on pod phase: Running, Pending, Failed, Succeeded, Unknown.
• sort_by accepts memory_usage or cpu_usage only.

Output: name, namespace, cluster, status, owner_kind, owner, node, restarts, cpu_usage, memory_usage, creation_time.

get-pod-detail needs all three of name, namespace, cluster. It is the tool that answers why a pod restarted — container statuses carry the restart reason, exit code, and last terminated state, which list-pods does not.

Workloads

The application-level view — one row per Deployment/StatefulSet/DaemonSet with its golden signals already joined from traces.

{ "namespace": "production", "kind": "Deployment", "sort_by": "error_rate", "sort_direction": "DESC" }

sort_by accepts rps, p95, errors, error_rate, restarts.

Output: name, namespace, cluster, kind, ready, desired, restarts, rps, p95, error_rate, issue_count, service_protocols.

Use this for a health sweep — it is one call for what would otherwise be an analyze-traces per workload. Drop to analyze-traces when you need a slice the summary doesn't have (by endpoint, by status code, by attribute).

list-issues

KubeSense's own issue detection — errors, latency, and connectivity problems between workloads. Prefer it over re-deriving problems from raw telemetry.

Output: issue_id, kind, cluster, primary_workload, primary_namespace, associate_workload, issue_reason, return_code, subtype, sum_issue_count, max_last_seen.

associate_workload is the other side of a connectivity issue — the dependency that primary_workload failed to reach.

get-infra-issues

Kubernetes-layer failures, from cluster events. This is the OOM / CrashLoop / probe-failure tool.

{ "namespace": "production", "workload": "checkout", "reason": "OOMKilling" }

Known reason values: OOMKilling, BackOff, Unhealthy, FailedScheduling, FailedMount, ImagePullBackOff, NodeNotReady. Omit reason to see all failure modes — narrow only once you know which one you're chasing.

Output: reason, type, workload, object, namespace, exit_code (crashes only), message, count, last_seen. Defaults to limit 50, max 200.

Layer routing: infra failures → this tool. Application errors and latency → analyze-traces / search-traces. What changed → get-recent-changes.

get-recent-changes

Image updates (deploys) and replica scaling, from cluster events. Usually the first thing to check in any investigation — "what changed right before it broke" is the cheapest hypothesis you will test.

{ "namespace": "production", "workload": "checkout", "kind": "image_update" }

kind is image_update or scaling; omit for both. Output: kind, workload, namespace, object, detail, when — where detail reads like kubesense: dev-v1.2.1279 -> dev-v1.2.1280 or replicas 1 -> 0. Defaults to limit 50, max 200.

Scope with namespace + workload. Both are optional but strongly recommended — an unscoped call across a busy cluster returns mostly noise.

Investigation Pattern

Symptom → context → cause, cheapest signal first:

1. get-recent-changes    namespace+workload → did we just deploy or scale?
2. get-infra-issues      same scope        → is the platform killing it (OOM, probes, sched)?
3. list-pods / get-pod-detail               → restart counts, exit codes, last state
4. analyze-traces / search-logs              → application-level errors and latency
5. analyze-metrics                           → confirm resource pressure quantitatively

Steps 1–2 are two cheap calls that resolve a large share of incidents outright. Reach for telemetry once they come back clean.

Rules

1. list-clusters before any clusters filter. The filter is unvalidated free text — a wrong name returns an empty result that looks exactly like "no data".
2. Names flow forward from list → detail calls. Never invent a pod, node, workload, or namespace name.
3. get-pod-detail requires name + namespace + cluster; get-workload-detail requires workload + namespace. Discover them with the matching list-* call.
4. Node sort_by uses the misspelling _precent; output columns use _percent.
5. Prefer list-issues / get-infra-issues over re-deriving problems from raw telemetry — the platform already did the detection.
6. Scope get-recent-changes and get-infra-issues with namespace + workload; unscoped calls are noisy.
7. Default window is 1 hour. If a result set looks empty, widen the window before concluding nothing happened.