{ "version": 2, "description": "TiDB Cloud data-plane architecture by tier (Dedicated, Starter/Essential serverless, Premium pool), plus metric routing. Use with cluster_meta after basic cluster info is known.", "shared_control_plane_pattern": { "summary": "Across tiers, the logical chain is consistent: TiDB parses/optimizes SQL and runs distributed plans; PD holds metadata and scheduling (and TSO); TiKV stores row data with Raft; TiFlash serves HTAP columnar reads (Raft Learner async replication); TiCDC captures changes for sync; TiProxy may sit in the SQL connection path where the product deploys it.", "notes": [ "Dedicated: direct component-to-component communication; topology visible to the user.", "Starter/Essential: platform abstracts nodes; isolation is logical via shared pools.", "Premium: resource pool shared by multiple logical clusters; keyspace isolates tenants inside the pool." ] }, "tiers": { "dedicated": { "labels": ["dedicated"], "cluster_type_hints": ["dedicated"], "cluster_type_v2": ["dedicated"], "architecture_summary": "Fixed-node deployment: compute and storage are tightly coupled; users manage scale-out/in, upgrades, restarts. Topology is explicit and controllable.", "core_components": [ { "name": "TiDB Server", "role": "SQL layer; MySQL protocol; parse, optimize, build distributed execution plans." }, { "name": "PD (Placement Driver)", "role": "Cluster metadata, data placement and topology, control UI surface, allocates transaction IDs (TSO path)." }, { "name": "TiKV Server", "role": "Distributed KV engine; stores data; supports distributed transactions." }, { "name": "TiFlash", "role": "Columnar extension for HTAP; data replicated asynchronously via Raft Learner." }, { "name": "TiCDC", "role": "Change data capture for downstream sync." }, { "name": "TiProxy", "role": "Connection maintenance / proxy where deployed in the architecture." } ], "relationships": { "call_flow": "TiDB accepts SQL, optimizes, plans execution; resolves ranges via PD; reads/writes go to TiKV; results return to the client.", "replication": "TiKV uses Raft for multi-replica consistency; TiFlash follows via Raft Learner.", "metadata": "PD stores cluster meta and issues scheduling commands based on TiKV state." }, "diagnosis_workflow": [ "Component health: Grafana dashboards per component.", "Logs: direct access to TiDB/TiKV/PD/TiFlash/TiCDC logs on instances.", "Performance: tune instance classes, counts, and configuration parameters." ], "metric_routing": { "all_components_cluster_id": "Use cluster_id for TiDB, TiKV, PD, TiFlash, and node metrics in typical dedicated flows." }, "notes": [ "Strongest direct observability; RCA often starts at component logs + metrics without pool abstraction.", "Prefer version-matched PSC / Grafana definitions for PromQL." ] }, "starter": { "labels": ["starter", "serverless", "shared"], "cluster_type_hints": ["shared"], "cluster_type_v2": ["starter"], "architecture_summary": "Serverless-style data plane: no fixed dedicated nodes visible; compute comes from shared pools; storage is distributed; tenant sees logical endpoints, not raw topology. Isolation is platform-level scheduling, not a dedicated cluster boundary.", "core_components": [ { "name": "TiDB Server", "role": "SQL layer for tenant workloads." }, { "name": "TiKV Server", "role": "Distributed storage." }, { "name": "PD Server", "role": "Metadata and scheduling." }, { "name": "TiFlash", "role": "Columnar / analytic queries where enabled." }, { "name": "TiDB Gateway", "role": "Service gateway into the shared plane." }, { "name": "Manager", "role": "Management component for the shared environment." }, { "name": "TiDB Worker", "role": "Background tasks (platform-scheduled)." }, { "name": "TiKV Worker", "role": "Remote compaction, import-related tasks, etc." } ], "relationships": { "shared_pool": "Multiple tenants share physical cluster capacity; logical isolation between tenants.", "task_scheduling": "TiDB Worker / TiKV Worker run background work; platform can autoscale capacity.", "import_optimization": "LDW-shared pool can handle small-table import patterns to avoid churn from repeatedly spinning ephemeral resources." }, "diagnosis_workflow": [ "Logs: typically via Grafana Loki for component logs (platform-mediated).", "Metrics: Prometheus for key service metrics; align PSC templates with serverless filters (e.g. keyspace_id).", "Storage model: logical vs physical separation supports multi-tenant isolation — interpret hotspots in tenant/keyspace context." ], "metric_routing": { "tidb_metrics_cluster_id": "Use the cluster_id of this tenant cluster.", "tikv_pd_tiflash_node_metrics": "Shared data plane: use PSC serverless PromQL as documented — do not add unsupported labels (e.g. control_plane_info in PromQL).", "keyspace": "Replace keyspace_id in templates with the value from cluster metadata when required." }, "notes": ["RU billing; coprocessor autoscaling differs from Dedicated."] }, "essential": { "labels": ["essential"], "cluster_type_hints": ["shared"], "cluster_type_v2": ["essential"], "architecture_summary": "Same broad serverless model as Starter: shared pools, logical endpoints, platform-managed scale. SQL traffic may pass through TiProxy; keyspace-scoped TiDB.", "core_components": [ { "name": "TiDB Server", "role": "SQL layer." }, { "name": "TiKV Server", "role": "Storage." }, { "name": "PD Server", "role": "Metadata / scheduling." }, { "name": "TiFlash", "role": "Analytics columnar path." }, { "name": "TiDB Gateway", "role": "Gateway into shared services." }, { "name": "Manager", "role": "Control-plane style management." }, { "name": "TiDB Worker", "role": "Background tasks." }, { "name": "TiKV Worker", "role": "Compaction / import-related workers." }, { "name": "TiProxy", "role": "Connection path and session handling — candidate bottleneck under high connection churn or proxy-heavy workloads." } ], "relationships": { "shared_pool": "Same pattern as Starter: multi-tenant shared physical resources with logical isolation.", "task_scheduling": "Workers + platform autoscale; import optimizations may use shared LDW-style pools." }, "diagnosis_workflow": [ "Logs via Loki; metrics via Prometheus with correct keyspace / serverless filters.", "When latency points to the SQL edge, validate TiProxy-related metrics and connection behavior." ], "metric_routing": { "tidb_metrics_cluster_id": "Use cluster_id.", "tikv_pd_tiflash_node_metrics": "PSC serverless-style PromQL without extra unsupported labels.", "keyspace": "Use keyspace_id from cluster metadata in PSC templates when required." }, "notes": [ "Treat TiProxy as a first-class suspect for edge latency or connection issues.", "RCU / capacity caps can throttle throughput — correlate with resource_manager metrics." ] }, "premium": { "labels": ["premium", "nextgen", "tidb-x premium"], "cluster_type_hints": ["nextgen-host", "premium"], "cluster_type_v2": ["premium"], "architecture_summary": "Pooled architecture: one physical resource pool hosts multiple logical clusters; isolation by keyspace inside the pool. Some components scale automatically; others are fixed per pool design.", "core_components": [ { "name": "TiDB", "role": "SQL layer; horizontal scale-out supported (per product limits); one keyspace maps to dedicated TiDB footprint." }, { "name": "TiDB Worker", "role": "Shared across keyspaces; autoscale; DXF tasks (import, ADD INDEX, etc.)." }, { "name": "TiKV", "role": "Shared across keyspaces; no autoscale in the same sense as TiDB tier; standard TiKV functions." }, { "name": "TiKV Worker", "role": "Shared; autoscale; remote compaction and serialized handling for IMPORT INTO / ADD INDEX style work." }, { "name": "Coprocessor Worker", "role": "Shared; autoscale; coprocessor offload from TiKV read path." }, { "name": "PD", "role": "Shared; no autoscale; metadata and scheduling." }, { "name": "TSO service", "role": "Shared; no autoscale; timestamps for transactions." }, { "name": "Scheduler (PD scheduling)", "role": "Shared; no autoscale." }, { "name": "TiProxy", "role": "Shared; no autoscale; connection maintenance and routing to TiDB." }, { "name": "TiFlash - write", "role": "TiFlash write path nodes." }, { "name": "TiFlash - compute", "role": "TiFlash compute for analytics." } ], "relationships": { "resource_sharing": "Multiple logical clusters (instances) share one physical pool; keyspace provides logical isolation.", "autoscale": "TiDB, TiDB Worker, TiKV Worker, Coprocessor Worker can autoscale with load; PD/TSO/Scheduler/TiProxy/TiKV core are pool-stable in typical designs.", "call_flow": "Client connections often land on TiProxy → routed to the right TiDB for the keyspace → TiKV for row storage; TiFlash serves HTAP queries." }, "diagnosis_workflow": [ "Metrics: Prometheus for per-component SLOs plus pool-level saturation.", "Logs: Loki across components; correlate by instance and keyspace.", "Autoscale: review autoscaler events vs latency/QPS — Coprocessor Worker and RCU ceilings are common RCA themes.", "Resource pool: watch aggregate pool load, not only a single logical cluster." ], "metric_routing": { "tidb_metrics_cluster_id": "Use the premium cluster_id for TiDB-tier metrics.", "tikv_pd_tiflash_tiflash_node_metrics": "Use parent_id (resource pool / nextgen-host id) as cluster_id in metrics API paths — not the premium cluster_id.", "premium_parent_id": "Required for TiKV/PD/TiFlash/node metrics; fetch from cluster detail if absent." }, "notes": [ "Coprocessor Worker autoscale limits and RCU throttling frequently appear in Premium performance cases.", "Separate TiFlash write vs compute when interpreting HTAP latency." ] } }, "tier_comparison": [ { "aspect": "Resource model", "dedicated": "Dedicated exclusive resources", "starter_essential": "Shared multi-tenant pool", "premium": "Pooled shared physical cluster per resource pool" }, { "aspect": "Node visibility", "dedicated": "Visible and user-managed", "starter_essential": "Not visible; platform-managed", "premium": "Partially visible; platform-managed pool" }, { "aspect": "Scale model", "dedicated": "Manual scale-out/in and config changes", "starter_essential": "Platform autoscaling / serverless scheduling", "premium": "Mixed: autoscale for selected roles (TiDB, workers, cop workers); fixed pool services (PD/TSO/TiProxy/TiKV core per design)" }, { "aspect": "Isolation", "dedicated": "Physical isolation per cluster", "starter_essential": "Logical isolation on shared infrastructure", "premium": "Logical isolation by keyspace inside one pool" }, { "aspect": "Control depth", "dedicated": "User controls topology and parameters", "starter_essential": "Platform controls infra; user tunes workload and SQL", "premium": "Platform manages pool; user tunes instance + workload within product limits" } ], "typical_use_cases": { "dedicated": "Enterprises needing full control, bespoke tuning, predictable dedicated capacity.", "starter_essential": "Dev/test, cost-sensitive, smaller workloads; Essential when TiProxy/gateway features match product SKUs.", "premium": "Elastic scale, multi-tenant style isolation with keyspaces, mixed workloads with HTAP and workers." }, "diagnosis_strategy_by_family": { "dedicated": "Start from component metrics + raw logs on nodes; shortest path from symptom to process.", "starter_essential": "Rely on platform metrics (Prometheus) and centralized logs (Loki); emphasize keyspace/RU and shared-pool contention.", "premium": "Combine logical-cluster metrics with resource-pool views; include autoscaler timeline and parent_id-scoped TiKV/PD series." }, "workflow_checklist": [ "Read deployType / cluster_type / cluster_type_v2 / parent_id / keyspace_id from cluster metadata.", "Select the tier section and apply metric_routing before TiKV/PD vs TiDB split.", "If premium, confirm parent_id for non-TiDB metrics; if starter/essential, confirm keyspace_id for PSC templates.", "Choose diagnosis_workflow and diagnosis_strategy_by_family consistent with the tier (direct logs vs Loki-first, pool vs tenant scope)." ] }