--- name: observability-k8s-investigation description: > Investigate Kubernetes workload, node, and control-plane issues using OTel telemetry (EDOT). Use when diagnosing pod failures (CrashLoopBackOff, OOMKilled, Error), node pressure, resource exhaustion, image pull failures, admission rejections, autoscaling anomalies, or correlating K8s state with application signals. OTel ingest path only — the legacy ECS Kubernetes integration shape is out of scope. compatibility: > Requires the `elastic` CLI (>= 0.2) with an Elasticsearch context, and Kubernetes telemetry ingested through EDOT / the OpenTelemetry kube-stack collector into OTel-receiver-namespaced data streams. The base floor is Elasticsearch 8.11 or later, or Serverless. One query uses the `VALUES()` aggregation, which is GA on Serverless but preview from 8.14 and GA only in 9.4 on Stack; a `VALUES()`-free rewrite is given at the point of use. Alert-state lookups additionally need a Kibana context. metadata: author: elastic version: 0.5.1 universal: true --- # Kubernetes Investigation Diagnose Kubernetes issues using OTel telemetry collected via EDOT (Elastic Distribution of OpenTelemetry) and the kube-stack collector. Correlate cluster state, pod runtime metrics, K8s events, application logs, and APM to identify root cause across the workload, node, and control-plane layers. ## Environment Configuration This skill executes Elasticsearch operations through the `elastic` CLI. If the [`elastic` CLI](https://github.com/elastic/cli#configuration) is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds. This skill references operations in HTTP-shorthand form (e.g., `GET /`, `GET /_cat/indices`, `GET /{index}/_mapping`, `GET /{index}/_settings/index.mode`, `POST /_query`). The [Operations](#operations) table at the end of this document maps each shorthand to the equivalent `elastic` CLI command — always use the CLI rather than calling the HTTP API directly. ### Analysis without cluster access The CLI check above gates _querying the cluster_ — it does not gate analysis. When the user has already supplied the evidence in their question (metric values, counts, status reasons, log lines, alert payloads, configuration), reason from that evidence and deliver the conclusion. When you genuinely do need data the user has not provided, still say what you would check and how — name the specific query, index, and field that would settle the question — and then ask for CLI setup. An answer that names the check is useful without a cluster; one that only asks for setup is not. Every ES|QL query in this skill and in [references/query-recipes.md](references/query-recipes.md) runs via `POST /_query`. Alert state is read with `GET kbn:/api/alerting/rules/_find`. Field-presence checks use `GET //_mapping` or `GET /_field_caps`. The [Operations](#operations) table maps each to its `elastic` CLI equivalent. ## Scope **In scope:** OTel-receiver-namespaced indices (`metrics-kubeletstatsreceiver.otel-*`, `metrics-k8sclusterreceiver.otel-*`, `logs-k8seventsreceiver.otel-*`, `logs-k8sobjectsreceiver.otel-*`) and OTel semantic conventions (`k8s.pod.name`, `k8s.namespace.name`, `k8s.container.restarts`). **Out of scope:** - The legacy Elastic Agent Kubernetes integration (`metrics-kubernetes.*`, `logs-kubernetes.*`, `kubernetes.*` fields). Being deprecated — do not author queries against these paths. - APM-layer analysis (service SLO breaches, transaction error rates, upstream dependency health). Different domain — once a K8s root cause is ruled in or out, hand off to the **observability-sre-triage** skill, which owns SLO status and burn rate, active alerting rules, throughput, latency, error rate, dependency health, and log funnelling. That is also the skill to use when the workload turns out not to be Kubernetes-hosted at all. - Cluster provisioning, capacity planning, cost optimization. Different domain. ## Guidelines These apply to every investigation. When in doubt, re-read them before writing the synthesis. **Absence of evidence is not evidence. Do not confabulate from empty results.** If log queries return 0 rows, logs are likely not collected or the pod has no recent lines — this does _not_ mean "dependency unavailable" or any other specific failure mode. Report `no_logs_available` and weight remaining signals accordingly. **Empty dependency data ≠ upstream healthy.** Services without APM instrumentation (load generators, workers) emit no destination metrics. Report `insufficient_dependency_data`, not "upstreams OK." **Co-symptoms are not causes.** Two services degrading simultaneously usually share an upstream, not a causal link. Only attribute causation when (a) one service's degradation clearly precedes the other's, and (b) the delta is large (>5× error rate, >3× latency). **OOMKilled ≠ memory leak by default.** The limit might simply be undersized for the workload's working set. Tell them apart by the shape of the memory curve: a monotonic climb to the limit that resets on each restart, with load flat against the prior week and no recent deploy, is the leak signature — commit to it at high confidence. Reach for a 7-day same-hour baseline when the shape is ambiguous — spiky, diurnal, or load-correlated — not as a precondition for every OOMKilled finding. **Error-termination ≠ application bug by default.** Check `k8s.container.cpu_limit_utilization` first. CFS throttling driving liveness probe timeouts is the most common misdiagnosis in this space. **Average CPU hides throttling.** A pod can look healthy at 40–60% average `cpu_limit_utilization` while being throttled severely at p99. Linux enforces CPU limits in 100ms periods; bursty workloads reach quota mid-period and stall. Look at max and p95, not only the average. **Restart count is boolean, not a counter.** `k8s.container.restarts` is pulled directly from the K8s API and can be pruned by the kubelet at any time, so the absolute value is unreliable. Treat it as `== 0` (no recent restarts) versus `> 0` (recently restarting); do not derive backoff timing or "linear versus exponential" patterns from it. Confirm the restart pattern via K8s `Killing` / `BackOff` events instead. **Prefer to report uncertainty over manufacturing confidence.** If the evidence is ambiguous, the synthesis should say so. Competing hypotheses are a valid output. **Equally, do not manufacture uncertainty.** The rule above is about ambiguous evidence, not about tone. When the pivotal signal is present and corroborated, commit to it at high confidence. Hedging an unambiguous finding down to "medium" is as much a defect as overclaiming. **Deliver the synthesis and stop.** State confidence once, in the HYPOTHESIS line — not again per bullet. Do not narrate which queries were run unless a result changed the conclusion, and do not restate the alert back to the reader. End on RECOMMENDED NEXT STEPS or DOWNSTREAM IMPACT; never close with an offer such as "want me to look further?". Follow-up work belongs in the recommendations list, phrased as a recommendation. ## Indices and fields ### Where to look | Signal | Index pattern | Use | | --------------------- | --------------------------------------------------- | ------------------------------------------------------------------- | | Pod/container runtime | `metrics-kubeletstatsreceiver.otel-*` | CPU, memory, network, filesystem. Utilization ratios. | | Cluster state | `metrics-k8sclusterreceiver.otel-*` | Restarts, phase, last-terminated reason, HPA, quota, node condition | | K8s events | `logs-k8seventsreceiver.otel-*` | Killing, BackOff, FailedScheduling, Evicted, image pull events | | K8s object snapshots | `logs-k8sobjectsreceiver.otel-*` | Deployment/service/configmap state over time | | Application logs | `logs-*.otel-*` | `body.text`, `severity_text`, filtered by `k8s.pod.name` | | APM | `traces-*.otel-*`, `metrics-service_*.otel-default` | Correlate via `service.name` + K8s resource attrs | | ML anomalies | `.ml-anomalies-*` | Memory-growth, restart-rate, throttle jobs (if configured) | ### Key fields Flat OTel paths work in ES|QL. Prefer the flat form for readability; the nested `resource.attributes.*` form is for raw log documents only. | Field | Index | What it is | | ------------------------------------------------ | --------------------------- | ------------------------------------------------------- | | `k8s.pod.name` | all k8s | Pod name | | `k8s.namespace.name` | metrics only | Namespace. Mapped but **null** on k8seventsreceiver | | `attributes.k8s.namespace.name` | k8seventsreceiver | Namespace on events — filter on this form there | | `k8s.container.name` | all k8s | Container within pod | | `k8s.deployment.name` | k8sclusterreceiver + others | Parent deployment | | `k8s.pod.phase` | k8sclusterreceiver | Pending=1/Running=2/Succeeded=3/Failed=4/Unknown=5 | | `k8s.container.restarts` | k8sclusterreceiver | Total container restart count | | `k8s.container.status.last_terminated_reason` | k8sclusterreceiver | `OOMKilled`, `Error`, `Completed`, `ContainerCannotRun` | | `k8s.pod.status_reason` | k8sclusterreceiver | Pod-level reason (`Evicted`, `NodeLost`) | | `k8s.container.memory_limit_utilization` | kubeletstatsreceiver | 0.0–1.0+ (can exceed 1 transiently before OOM) | | `k8s.container.cpu_limit_utilization` | kubeletstatsreceiver | 0.0–N (frequently >1 under CFS throttling) | | `k8s.pod.memory_limit_utilization` | kubeletstatsreceiver | Whole-pod aggregate; see the note below before using it | | `k8s.pod.cpu_limit_utilization` | kubeletstatsreceiver | Whole-pod aggregate; see the note below before using it | | `k8s.pod.memory.usage` / `.working_set` | kubeletstatsreceiver | Bytes | | `k8s.node.condition_memory_pressure` | k8sclusterreceiver | 1 = pressure, 0 = ok | | `k8s.node.condition_ready` | k8sclusterreceiver | 0 = NotReady | | `k8s.hpa.current_replicas` / `.desired_replicas` | k8sclusterreceiver | HPA state | | `attributes.k8s.event.reason` | k8seventsreceiver | Event reason (filter on this) | | `body.text` | k8seventsreceiver / logs | Event message / log message | | `k8s.object.name` | k8seventsreceiver | involvedObject name (log attribute, use flat form) | ### Container-level against pod-level limit utilization Read limit utilization at the **container** level. `k8s.container.cpu_limit_utilization` and `k8s.container.memory_limit_utilization` are the default; the pod-level pair is a different measurement, not a synonym. The receiver emits the two families on **separate documents in the same data stream**: pod-level fields appear on documents that carry no `k8s.container.name`, and container-level fields appear only on documents that do. A `STATS ... BY k8s.container.name` therefore returns `null` for every pod-level field, and the reverse holds too. Measured over one hour on a live 9.6.0 cluster: of 42,240 documents without a container name, 360 carried `k8s.pod.cpu_limit_utilization` and none carried the container field; of 18,240 documents with a container name, 900 carried the container field and none carried the pod field. Availability differs too. Container-level utilization is emitted for each container that declares the limit, while the pod-level aggregate requires **every** container in the pod to declare it. Across two live clusters over three hours, no pod carried the pod-level field without also carrying the container-level one, while 27 pods carried the container-level field with the pod-level field absent — every one of them a multi-container pod in which only some containers declared limits. A pod-level throttling check on a sidecar-injected pod silently returns `null`. | Cluster | Container level only | Both levels | Neither | Pod level only | | ------------- | -------------------- | ----------- | ------- | -------------- | | forge-factory | 18 | 7 | 44 | 0 | | k8s-demo | 9 | 6 | 40 | 0 | Use the pod-level fields only when the question is genuinely about the pod as a whole — total consumption against the sum of its containers' limits — and only after confirming they are populated. **observability-sre-triage** applies the same rule, so the two skills return the same answer for the same pod. ### Field availability Several fields above are off by default in stock kube-stack collectors and require explicit configuration. Verify presence with `GET //_mapping` or `GET /_field_caps` before relying on them; if absent, fall back as noted and call out the substitution in the synthesis. | Field | Why it might be missing | Fall-back | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `k8s.container.status.last_terminated_reason` | Optional metric in k8sclusterreceiver; gated behind `metrics_collected.metadata` config. | Infer from K8s `Killing` / `OOMKilling` events in `logs-k8seventsreceiver.otel-*` and exit codes in app logs. | | `k8s.pod.status_reason` | Same — optional metric on k8sclusterreceiver. | Infer from events: `Evicted`, `NodeLost`, `Preempted`. | | `k8s.container.cpu_limit_utilization` / `memory_limit_utilization` | Only emitted for a container that declares the corresponding limit, and only when the kubeletstatsreceiver metric is enabled. | `k8s.pod.cpu.node.utilization` / `k8s.pod.memory.node.utilization` express consumption as a fraction of node capacity and are emitted whether or not limits are declared; or trend absolute `container.cpu.usage` / `container.memory.usage` against a baseline. Both fall-backs live on the pod-level documents, so group by `k8s.pod.name`, not `k8s.container.name`. | | `k8s.pod.cpu_limit_utilization` / `memory_limit_utilization` | Requires every container in the pod to declare the limit, so it is absent on most multi-container pods. | Use the container-level fields, which are available strictly more often. | | `k8s.node.condition_memory_pressure` | Gated behind k8sclusterreceiver `node_conditions_to_report` (default omits this). | Compare `k8s.node.memory.usage` against `k8s.node.allocatable_memory`, or look for `Evicted` events on the node. | If a fall-back is used, note it in the synthesis (for example, `(via memory.usage; limit_utilization not collected)`) so the reader knows the signal is indirect. ## ES|QL gotchas Before writing queries, know these. Each of them silently produces wrong answers rather than failing loudly. **`VALUES()` returns scalar for single distinct value, array for multiple.** Templating that assumes array shape (for example, `| first`) extracts the first character of the string when scalar. Use `MV_FIRST(VALUES(...))` or handle both. **`VALUES()` is newer than this skill's base floor.** It is GA on Serverless, but on Stack it is preview from 8.14.0 and GA only in 9.4.0, and it does not exist at all below 8.14. Check `GET /` before using it: `build_flavor: "serverless"` means it is available, otherwise read `version.number`. Where it is not available, move the field into the `BY` clause instead of aggregating it — one row per distinct value carries the same information: ```esql | STATS restarts = MAX(k8s.container.restarts), phase = MAX(k8s.pod.phase) BY term_reason = k8s.container.status.last_terminated_reason | SORT restarts DESC | LIMIT 10 ``` **`PERCENTILE` does not work on OTel `histogram` type** (as of 8.15). For APM duration percentiles, use `AVG` on the `aggregate_metric_double` summary field (`AVG(transaction.duration.summary)` divides sum by value_count). For true percentiles, fall back to Kibana Query DSL. **`COUNT(agg_metric_double)` returns `value_count` (events), not doc count.** `SUM(field)` gives the sum component; `AVG(field)` gives sum/value_count. Do not use `SUM(transaction.duration.summary)` as an event-count proxy — it returns total duration. **K8s metrics use flat OTel field paths in ES|QL.** `k8s.pod.name`, no