# ISS-0096: `kube_pod_info` Metric Not Supported by Data Proxy

## Background

Discovered in workspace ws-1779849323231-f013bf8a9 (prod, `investibook.com`, created by
nizheming@pingcap.com). The user reported via `/issue`:

> kube_pod_info data proxy 不支持

Source: GitHub issue #603.

## Observed Problem

When the agent or user queries the `kube_pod_info` metric through the Clinic/data proxy,
the proxy returns an error indicating this metric is not supported. `kube_pod_info` is a
standard Kubernetes metric that provides pod metadata including:
- `pod` name
- `node` name (which physical node the pod runs on)
- `namespace`
- `created_by_kind` / `created_by_name`

This metric is valuable for:
1. Mapping TiKV instance labels (e.g., `db-tikv-19`) to actual Kubernetes node names.
2. Correlating pod restarts with node-level events.
3. Identifying AZ (Availability Zone) for hotspot analysis (related to ISS-0069).

## Root Cause

The Clinic data proxy (which provides a Prometheus-compatible API for TiDB Cloud metrics)
has an allowlist of supported metrics. `kube_pod_info` is a Kubernetes-level metric
exposed by `kube-state-metrics`, which may not be included in the Clinic proxy's metric
allowlist for TiDB Cloud Dedicated/Premium clusters.

Possible reasons for exclusion:
- `kube_pod_info` exposes infrastructure topology that Clinic considers out-of-scope.
- The metric requires access to the Kubernetes control plane, not just the TiDB cluster
  metrics store.
- The Clinic API's metric routing doesn't proxy requests for `kube_*` namespace metrics.

## Fix Plan

1. **Confirm the exact error response from data proxy for `kube_pod_info`:**
   - Test: `clinic metrics query --cluster-id <ID> --query 'kube_pod_info'`
   - Document the HTTP status code and error message.

2. **Option A — Add `kube_pod_info` to data proxy allowlist:**
   - If the metric is available in the underlying monitoring stack (VictoriaMetrics/
     Prometheus), file a request with the Clinic/data-proxy team to add `kube_pod_info`
     to the allowlist.
   - This unblocks pod-to-node mapping, AZ identification (ISS-0069), and restart analysis.

3. **Option B — Use alternative pod metadata source:**
   - The TiDB Cloud cluster API (`/api/v1beta/clusters/{id}/nodes`) may provide node-to-
     instance mapping without requiring `kube_pod_info`.
   - Update `collect_evidence.py` A0 segment to query the cluster nodes API and build the
     instance → node → AZ mapping from there.

4. **Update SKILL.md to document the limitation:**
   - Until `kube_pod_info` is available, document that pod-to-node mapping must be done
     via the cluster nodes API, not via Prometheus metrics.
   - Add a note: "Do not attempt to query `kube_*` metrics via Clinic data proxy — they
     are not supported. Use TiDB Cloud cluster API for node topology."

## Verification

After fix:
- `clinic metrics query --cluster-id <ID> --query 'kube_pod_info'` returns actual pod
  metadata rows, not an error.
- `collect_evidence.py` can map TiKV instance labels to Kubernetes node names in the
  evidence summary.