PD GRPC Service

PD GRPC 接口图解

目前 PD 对外暴露的接口主要分为两类：

GRPC

HTTP restful API

本文主要介绍 PD 6.0.0 对外暴露的 GRPC 接口信息，通过本文，你可以：

通过接口，全面了解 PD 提供的服务内容

可以作为一个导读入口，开始源码阅读，深入了解某个部分或开启 PD developer 之旅。

概览

详细接口分类

GetMemebers

接口说明： 该接口主要用于获取当前 PD 的实例信息，包括PD 的 leader 信息、子服务信息。

请求参数：无

请求返回：

Member：当前集群中所有实例的基本信息

etcd_leader: 当前 etcd 集群所在 leader 节点信息。

Leader: 当前 PD 集群的 leader 节点信息。 pd 选 leader 时，只有 etcd 的 leader 参会参与 leader 的竞选，因此该理论上与 pd leader 节点保持一致，但存在极端情况。

tso_allocator_leaders: tso 各个 location 对应的 tso 分配器的 leader 信息

TSO

TSO (Get)

接口说明： 按数据中心获取全局唯一递增时间戳

请求参数：

dc_location 数据中心位置

count 当前想要获取的时间戳个数

请求返回

count 当前给出的时间戳个数

timestamp 时间戳信息

physical 逻辑时间戳

logical 逻辑时间戳

suffix_bits 用于计算 logical 的后缀长度, 主要用作全局区分。

SyncMaxTs

请求说明：同步所有 DC 之间的 MaxTS. 主要实现两个需求：

获取当前系统中最大 localTSO

确保当前系统中的 localTSO 都大于 req.MaxTS

请求参数：

MaxTs 当前要设置的 maxts 值

Skip-check: 是否跳过检查，若为 false, 会

请求返回：

maxLocalTS

如果 skip-check = false, 则尝试获取当前系统最大 TS

如果发现当前系统的 max-ts 大于 req.max-ts, 则不做更新，并获取当前系统最大的 local-max-ts.

否则，尝试将所有 DC 的时间更新到 req.max-ts,若 dc.current-ts > req.max-ts , 则无需更新。

SyncdDcs 数据中心列表

GetDCLocationInfo

请求说明：获取指定 dc-location 的 信息

请求参数： string dc-location

请求返回：dc-location 基本信息

Suffix int

max_ts timestamp

集群管理

启动

Bootstrap

接口说明：启动当前集群

请求参数:

store：集群中 store 基本信息

region: 集群中 region 基本信息

请求返回

IsBootstrapped

接口说明：咨询当前集群是否启动成功

请求参数：

请求返回：当前集群是否已启动成功

Raft Cluster

ClusterConfig

GetClusterConfig

请求说明：获取集群基本信息

请求返回：cluster 信息，主要包括

Id 集群唯一 ID

MaxpeerCount 每个 region 最多的 peer 数，不足时会自动 balance

PutClusterConfig

请求说明：配置 cluster 的副本数

请求参数：cluster 信息，同 Get 请求的返回值

Question：

这里副本数这个参数看起来外面 tikv 在用？PD 未找到具体使用的地方

处理请求时只对 cluster ID 做了校验，是否需要检查 maxpeercount 是否合理？

Stores

PutStore

接口说明： 创建 store。关键检查条件：

如果当前集群中存在相同 ID 的 store 且状态为已删除，返回失败

如果 placementrule 未打开，但 store 为 tiflash node 失败（使用 tiflash 需要 placement-rule 启用）

如果存在相同 address 但 ID 不同的 store, 返回失败

集群中定义的 location - label 未配置全，返回失败。

请求参数：store 基本信息

请求返回：告知 tikv 当前集群的 replication-mode，目前支持两种模式：

标准模式：MAJORITY

DR_AUTO_SYNC：Replicate logs among 2 DCs.

GetStore

接口说明：根据 ID 获取集群中对应 store 的信息

请求参数：store_id

请求返回：

当前 store 基本信息

当前 store 统计信息, 如容量，region 个数，SendingSnapCount，KeysWritten，CpuUsages 等基本信息

GetAllStores

接口说明：获取当前系统中的 store 列表

请求参数：exclude_tombstone_stores 是否包含 tombstone 的 store

请求返回: store 的原信息列表，同 GetStore

StoreHeartbeat

接口说明：store 日常心跳上报，确保 store 处于活跃状态

请求参数：

StoreStats stats 基本状态，基本信息如 capacity,Available,region_count,sending_snap_count,receiving_snap_count, start_time ...

StoreReport store_report store 当前的副本列表及状态，只有在 unsafe recovery 才会有此项内容

replication_modepb.StoreDRAutoSyncStatus dr_autosync_status 当前系统恢复的状态

请求返回：

replication_status： 当前集群的 replication-mode

cluster_version： 当前集群版本号

require_detailed_report unsafecovery 时返回

recovery_plan，unsaferecovery 时返回

ReportMinResolvedTS

请求说明：上报 store 的最小 resolvedTS, 会落到 store 的属性里

请求参数：

storeID

minResolvedTS

Cluster

RegionHeartbeat

接口说明：Region 心跳上报, 同步 region 基本信息(只有 region leader 会上报心跳, stream req, 一次可能上报多个 region 的心跳)

请求参数： Region 基本信息，如：

Region: 基本信息，ID,start_key,end_key,epoch,peers

Leader: region 的 leader 基本信息（ID，storeID,role）

Peer 基本信息，主要分两类

Pending peers 还没到 follower 状态的 peer

DownPeers: leader 认为挂掉的 peer 信息，包括：

Peer 基本信息（ID,storeID,role）

downSeconds

Region 本身的数据写入情况，如

bytes_written/read 当前时间窗口

keys_wrritted/read 当前时间窗口

Approximate size/keys 总

term 当前 raft group 的 term

Replication-status

Cpu-usage

...

请求返回：如果发现当前 region 需要调度，返回对应调度指令, 每个 region 一次只会下发一个 operator

ChangePeer： RemovePeer/AddNode/AddLearnerNode

TransferLeader

Merge

Split-region

ChangePeerV2: replacing peers/demoting voter directly

Region 基本信息读请求 GetRegion/GetPrevRegion

接口说明： 获取当前/前一个 region 基本信息、状态、负载情况

请求参数： region-key, 是否需要 buckets 信息

请求返回

Region: 基本信息

Leader

down_peers/pending_peers

buckets(if needed): 按 bucket 为最小单位的负载情况信息（write/read-key/size）

GetRegionByID

接口说明：同 GetRegion，区别是通过 region-id 获取

ScanRegions

接口说明：根据指定的 key 返回获取 region 列表

请求参数：

start-key/end-key

Limit, 为空时，返回所有

请求返回

Region-metas

Region-leaders

Regions

说明：这里请求返回的组织形式有点奇怪

ReportBuckets

请求说明：上报 bucket 基本信息

请求参数（stream）：buckets 基本信息

region_id

Keys []string

BucketStats []stat

period_in_ms: 数据采集的间隔

Split Region AskBatchSplit

请求说明：发起将 region 切成指定份数的请求，请求返回成功后，最终 split 不一定成功。

请求参数：region 基本信息，split-count

请求返回：预切分好的 region ID 及peer ID 列表：split-ID (peers-ids,region-id) list

ReportBatchSplit

请求说明：tikv 汇报 split region 成功，PD 这边打印日志，方便查询 split region 请求是否已经生效成功。

请求参数：regions 被切分的 regions 信息

请求返回：基本认证 header.

SplitRegion

请求说明：根据指定 key 列表分裂相关 regions，请求返回时，split 已经物理完成。

请求参数：

splitkeys: 指定 key 列表

retry_limit: 重试次数

请求返回：

regions_id: 新生成的 region 列表

finished_percentage: 完成率

ScatterRegion

请求说明：打散 region

请求参数：

Group 组名，如果非空，则会在 group 级别进行打散，不存在，则整个集群级别打散。

regions_id 需要打散的 region 编号

Retry-limit 每个 region 重试次数

Region-id 历史参数，当 regions-id 为空时，当前 region 为需要打散的 region

region,leader ：需要打散的 regiion 信息，当 PD 找不到需要打散的 regiion 时（region-id) 使用。举例：PD 尚未收到 regiion 的心跳上报。处理逻辑如下：当 regions-id 为空，region-id 为空时，当前信息组织成新的 region 进行打散。

请求返回：finished-percentage: 请求完成率，成功的 regions 个数/总 regions 个数

SplitAndScatterRegions

请求说明：根据指定的 key 切分 region 且打散 SplitRegions+ScatterRegion

请求参数:

splitkeys: 指定需要切分的 key 列表

Group 组名，如果非空，则会在 group 级别进行打散，不存在，则整个集群级别打散。

Retry-limit 重试次数

请求返回

regions_id: 新生成的 region 列表

split_finished-percentage: 请求完成率

scatter_finished-percentage: 请求完成率

SyncRegions（stream）

请求说明：向 PD 发起同步 region 信息的请求，一般用于大集群处理, 以及当 pd 中使用 levelDB 替代 ETCD 存储 region 信息时，PD 间 region 信息的同步。无法保证强一致性。

请求返回：各个 region 信息。。同步 region 基本信息

GetOperatorRequest

请求说明：获取指定 region 正在执行的 operator 状态

请求参数：region_id

请求返回：当前 operator 的基本信息和状态

region_id

Desc

status(success,timeout,cancel,replace,running)

kind(是否是 admin 发起的，优先级等)

GC

GetGCSafePoint

请求说明： 获取当前系统的 gc safepoint, 该值通过接口 UpdateGCSafePoint 接口设置

请求返回：safe-point

UpdateGCSafePoint

请求说明：设置 gc safepoint 信息，只有当需要设置的 safepoint 大于当前系统中的 safepoint 时，才会设置成功。

请求参数：

safe_point 当前要设置的 safepoint.

请求返回：

new_safe_point 当前系统中的 safepoint

UpdateServiceGCSafePoint

请求说明：为指定 service 存储可安全 gc 的 safepoint. 成功的条件是当前要设置的 safepoint 大于等于 service 中最小的 safepoint

请求参数：

service_id

TTL，TTL 为负数表示删除对应的 safepoint.

safe_point, 表示对 service 来说，当前 safepoint 之前的数据可以 GC 掉

请求返回：当前系统中 safepoint 最小的那个 service 信息, 该 minsafepoint 会永远向前滑动不会回退

service_id

ttl

MinSafepoint

GlobalConfig

看起来这里是对 ETCD 的简单封装，将需要的配置项放在 /global/config 下面，通过下面三个接口来实现查询、更新及服务发现的功能。

StoreGlobalConfig

接口定义：存储 key-value 配置项到 PD

参数：items []items,items 内容包括

Key

Value

error(没有使用)

LoadGlobalConfig

接口定义：获取 /global/config 下指定 keys 对应 的 values

请求参数：

Names []string 需要的 key 的名称

请求返回：当前需要的 keys 对应信息

Key

Value

error(查询该 key 过程中遇到的错误或 NOT found)

WatchGlobalConfig

请求说明：监听 /global/config 目录

请求返回：当前目录下发生变化的 key-value 信息