---
name: get-k8s-resource
description: |
  List/get one K8s Kind on Dedicated CP or DP via Ops
  dedicatedK8sResources (GVK, selector, detail/events). Use for Pods,
  APPBox, labels, field filters, or CP/DP inspection. For curated
  Cluster CR / scale_status_cm by cluster_id only, use get-cluster-cr.
---

# Action Type

`read-only`

- This subskill only queries backend data.
- It must not trigger any mutable API.

# Prerequisite

**You MUST read `mechanisms/extend-devops-api.md` (located in this skill's
root directory) in full before executing any action in this subskill.**

This mechanism document defines:
- How to resolve the `devops_http.sh` provider script path
- Path resolution failure handling (never glob or search)
- Token pre-check requirements
- Required argument workarounds

Do not proceed without reading it. Do not guess or search for provider file
paths — the mechanism document contains the exact resolution formula.

# Reuse Mechanism

This subskill follows `mechanisms/extend-devops-api.md` in `transport-only`
mode and reuses `devops_http.sh` from installed `devops-api` skill directories.

# Boundary

- Use **this** subskill for arbitrary Kind, CP/DP, selectors, detail/events.
- Use **`get-cluster-cr`** for curated `cluster_cr` / `scale_status_cm` by
  `cluster_id` only — not as a default Cluster CR shortcut via GVK Get.

# Available Actions

## List Dedicated K8s Resources

List or get **one** Kind per request on Dedicated regional-server CP or DP.

API Path: `/cluster/dedicatedK8sResources`

Method: `POST`

Field semantics, limits, and error table: see `reference.md` in this
subskill directory (read when needed).

### Interface Details

- Routing query (one of):
  - `region` + `cloud_provider` (logical region name, e.g. `us-west-2` + `aws`)
  - `cluster_id` (Dedicated cluster; resolves region/cp)
- Body (protojson **camelCase**), required:
  - `planeType`: `CONTROL_PLANE` or `DATA_PLANE`
  - `gvk.kind` (PascalCase); `gvk.group` / `gvk.version` optional
  - `selector` (may be `{}`)
- Body optional:
  - `dataPlane` (required for `DATA_PLANE` unless query `cluster_id` auto-fills
    `dataPlane.clusterId`)
  - `option.detail` (default false → TEXT table; true → YAML)
  - `option.events` (only with `detail=true`)
  - `option.maxItems`
- Optional input:
  - `env`: `prod` | `staging` | `dev`. Default: `prod`.
- `devops_http.sh` path:
  - `--path /cluster/dedicatedK8sResources`
  - `--method POST`
  - `--query` for routing params
  - `--body` for ListK8sResourcesRequest JSON

### kubectl Analogy

Three output modes map to common kubectl read patterns:

| Mode | Request | Approx. kubectl | Output |
|------|---------|-----------------|--------|
| Summary | `option.detail=false` (default) | `kubectl get <kind> [-n ns] [-l ...] -o wide` (no ns ≈ `-A`) | `TEXT` table |
| Detail YAML | `option.detail=true` | `kubectl get <kind> ... -o yaml` | `YAML` |
| Detail + events | `detail=true` + `events=true` | describe-style Events (not full `kubectl describe` UI) | YAML `{resource, events}` |

`selector.name` is Get-by-name (ignores `label`/`field`); the three modes still apply.

### Recommended Call Patterns

1. Start with **Summary** (`detail=false`). Narrow with namespace/label and
   `maxItems` before escalating.
2. Escalate only when needed: **Detail YAML**, then **Detail + events** if
   Events are required.
3. One Kind per request. Do not batch unrelated GVKs in one call.
4. Prefer query `cluster_id` for DP when the user already has a Dedicated
   cluster ID (handler injects `dataPlane.clusterId` when empty).

### Output Formatting

- **Do not** parse or rewrite the `content` field manually.
- Pipe `devops_http.sh` JSON through
  `scripts/format-k8s-resources.sh` in this subskill directory
  (`get-k8s-resource/scripts`).
- The script prints meta (`content_type`, `item_count`, `truncated`, `hints`)
  then the raw `content` string.
- Present the script's stdout directly to the user without further LLM
  post-processing of `content` bodies.

### Verification Points

- DevOps envelope success (`errcode` is 0 when present).
- Report `item_count`, and surface `truncated` / `hints` when set.
- Server GK policy is deny-by-default; disallowed Kind fails at the API —
  do not invent an allowlist locally.

### Example Invocations

Where `<this-subskill-root>` is `<toolkit-skill-root>/get-k8s-resource`.

**CP — APPBox summary (region + cloud_provider):**

```bash
bash <provider-skill-root>/scripts/devops_http.sh \
  --env dev \
  --method POST \
  --path /cluster/dedicatedK8sResources \
  --query "region=us-west-2&cloud_provider=aws" \
  --body '{
    "planeType": "CONTROL_PLANE",
    "gvk": {"group": "dedicated.regionalserver.tidbcloud.com", "kind": "APPBox"},
    "selector": {},
    "option": {"detail": false, "maxItems": 20}
  }' \
  --header "X-Request-ID: k8s-resource-cp" \
| bash <this-subskill-root>/scripts/format-k8s-resources.sh
```

**DP — Pod summary via cluster_id:**

```bash
bash <provider-skill-root>/scripts/devops_http.sh \
  --env dev \
  --method POST \
  --path /cluster/dedicatedK8sResources \
  --query "cluster_id=123456" \
  --body '{
    "planeType": "DATA_PLANE",
    "gvk": {"kind": "Pod"},
    "selector": {"namespace": "tidb-admin"},
    "option": {"detail": false, "maxItems": 50}
  }' \
  --header "X-Request-ID: k8s-resource-dp" \
| bash <this-subskill-root>/scripts/format-k8s-resources.sh
```

**DP — Get-by-name with detail YAML:**

```bash
bash <provider-skill-root>/scripts/devops_http.sh \
  --env dev \
  --method POST \
  --path /cluster/dedicatedK8sResources \
  --query "region=us-west-2&cloud_provider=aws" \
  --body '{
    "planeType": "DATA_PLANE",
    "dataPlane": {"clusterId": "123456"},
    "gvk": {"group": "cloud.pingcap.com", "kind": "Cluster"},
    "selector": {"namespace": "tidb123456", "name": "db"},
    "option": {"detail": true}
  }' \
  --header "X-Request-ID: k8s-resource-get" \
| bash <this-subskill-root>/scripts/format-k8s-resources.sh
```