---
name: clinic-cluster-metadata
description: |
  Clinic cluster lookup, org/tenant id distinctions, deployment type, and topology guidance.
---

# Cluster metadata

Use the parent CLI command:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py cluster-metadata --help
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py search clusters --help
```

Typical use:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py search clusters \
  --tenant-id <tenant_id>

python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py cluster-metadata \
  --cluster-id <cluster_id> \
  --include-components

python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py topology-snapshot \
  --cluster-id <cluster_id> \
  --at <timestamp>
```

Use `--include-components` whenever the task asks for TiDB / TiKV / PD /
TiFlash topology, runtime image tag, node count, CPU, memory, or storage details
such as IOPS / throughput. This command treats Clinic topology as the source of
truth and calls the `/resource-pool/components` topology path for dedicated,
resource-pool, premium, and BYOC clusters when available.

Use `topology-snapshot` whenever the user asks for topology or CPU core count at
a historical timestamp. Current Clinic topology is not historical evidence. The
snapshot command combines:

- point-in-time CPU quota / maxprocs metrics at `--at`;
- nearby Activity Hub topology-change events such as scale / resize / capacity
  changes;
- current topology only as a comparison reference.

If Activity is partial or unavailable, say that the historical snapshot is based
on metrics only and that current topology must not be presented as the state at
`--at`.

For timezone-bearing user input, keep the timestamp as an ISO8601 string when
calling the CLI. Example: use `--at "2026-06-30T12:00:00+08:00"` for
`2026-06-30 12:00 UTC+8`. Do not manually convert this to Unix epoch before the
CLI call unless the user already provided epoch seconds; manual conversion has
caused wrong-year queries.

When interpreting `topology-snapshot` output:

- `summary.metric_query_type=instant` means node/core metrics are evaluated by
  a Prometheus instant query at `summary.at`. Prometheus may use the nearest
  recent sample within its lookback window; use Activity Hub as change evidence
  around scale boundaries.
- `metric_window` is report metadata only; do not describe it as a range window
  used to count nodes.
- Prefer `instance_count` / `instances` from the snapshot when reporting node
  count. `instance_count` is the full deduplicated count; `instances` is a
  bounded evidence sample and may be truncated when `instances_truncated=true`.
  Use `series_count` as a fallback only when instance labels are absent.
- If `summary.historical_metrics_complete=false` or a requested component has
  `historical_metric_available=false`, the historical metric evidence is
  insufficient for that component. Do not run `cluster-metadata
  --include-components` as a fallback to fill the historical node/core answer.
  Current topology can be mentioned only as a current reference.
- No Activity Hub topology events in the searched window does not by itself
  prove that current topology equals the historical timestamp.
- If current topology differs from the point-in-time metric count, say only that
  current topology cannot replace historical evidence. Do not claim a scale-in
  or scale-out happened unless Activity Hub or another event source shows that
  topology change.
- Use the parsed `summary.at` / `snapshot.at` value from the CLI as the
  canonical epoch. Do not manually restate an epoch unless you have verified the
  timezone conversion.

## Key concepts

| ID | User-facing | Meaning |
| --- | --- | --- |
| `tenantID` | yes | Tenant / organization id users may reference. |
| `orgID` | no | Clinic internal id used by some Clinic APIs. |
| `clusterID` | yes | Cluster id. |
| `parentID` | no | Resource pool id for Premium / BYOC tenant clusters. |
| `clusterDeployTypeV2` | yes | Deployment type used for user-facing classification. |

## Lookup rules

- When a user gives a tenant id, use `search clusters --tenant-id <tenant_id>`.
  This filters exact `tenantID`; do not treat `orgID` as the tenant id.
- When a user gives a cluster id, prefer exact cluster lookup through `--cluster-id`.
- Do not assume the first search result is the target cluster.
- Branch clusters can appear beside numeric cluster ids; filter exact `clusterID` before using fields.
- For shared / starter / essential clusters, tenant-scoped TiDB/TiKV/PD topology is usually unavailable. Use metadata plus metrics/logs instead.

## Topology rules

| Cluster type | Topology expectation |
| --- | --- |
| Dedicated | `--include-components` queries the topology path for the current cluster. |
| Resource Pool | `--include-components` queries resource-pool components for the current cluster. |
| Premium / BYOC tenant | `--include-components` queries the current cluster by default; use `--resource-pool-scope parent` only when the question is explicitly about the parent resource pool. |
| Shared / starter / essential | Do not expect node-level topology from Clinic metadata. |

`--resource-pool-scope auto` is kept as a compatibility alias of `current`.
Shared / starter / essential clusters return an error for topology requests; use
cluster metadata plus metrics/logs instead.

For historical questions, do not pass an unsupported `--at` flag to
`cluster-metadata`; use `topology-snapshot --at ...`.