From b7d614e9c22b9526e818f7453d51d697523b493f Mon Sep 17 00:00:00 2001 From: disksing Date: Wed, 6 Nov 2019 20:53:42 +0800 Subject: [PATCH] placement: add API support (#1894) Signed-off-by: disksing --- docs/api.html | 2 +- server/api/api.raml | 134 ++++++++++++++++++++++++++- server/api/router.go | 9 ++ server/api/rule.go | 210 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 353 insertions(+), 2 deletions(-) create mode 100644 server/api/rule.go diff --git a/docs/api.html b/docs/api.html index 6c1dbe1e45a..79602c773c6 100644 --- a/docs/api.html +++ b/docs/api.html @@ -166,4 +166,4 @@ .resource-modal li > ul { margin-bottom: 1em; } -

Placement Driver API API documentation version v1

http://{pdAddr}/pd/api/{version}

  • pdAddr: required (string)

    The PD server address, formatted as 'host:port'.

  • version: required (v1)

/cluster/status

Cluster status.

get

get

Get cluster status.

/version

The version of PD server.

get

get

Get the version of PD server.

/status

The build info of PD server.

get

get

Get the build info of PD server.

/diagnose

Diagnostic information of the cluster.

get

get

/members

The PD servers in the cluster.

get

get

List all PD servers in the cluster.

delete post

A specific PD server.

delete

Remove a PD server from the cluster.

post

Set leader priority of a PD member.

Remove a PD server from the cluster.

URI Parameters

  • name: required (string)

HTTP status code 200

The PD server is successfully removed.

HTTP status code 400

The input is invalid.

HTTP status code 404

The member does not exist.

HTTP status code 500

PD server failed to proceed the request.

Set leader priority of a PD member.

URI Parameters

  • name: required (string)

Body

Media type: application/json

Type: object

Properties
  • leader-priority: required (integer)

HTTP status code 200

The leader priority is updated.

HTTP status code 400

The input is invalid.

HTTP status code 404

The member does not exist.

HTTP status code 500

PD server failed to proceed the request.

delete

A specific PD server.

delete

Remove a PD server from the cluster.

Remove a PD server from the cluster.

URI Parameters

  • id: required (integer)

HTTP status code 200

The PD server is successfully removed.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/leader

The leader PD server of the cluster.

get

get

Get the leader PD server of the cluster.

post

post

Transfer leadership to another PD server.

Transfer leadership to another PD server.

HTTP status code 200

The transfer command is submitted.

HTTP status code 500

PD server failed to proceed the request.

post

post

Transfer leadership to the specific PD server.

Transfer leadership to the specific PD server.

URI Parameters

  • nextLeader: required (string)

HTTP status code 200

The transfer command is submitted.

HTTP status code 500

PD server failed to proceed the request.

/health

Health status of PD servers.

get

get

/config

PD cluster configuration.

get post

get

Get full config.

post

Update a config item.

Update a config item.

Body

Media type: application/json

Type: object

HTTP status code 200

The config is updated.

HTTP status code 500

PD server failed to proceed the request.

get post

Schedule configuration.

get

Get schedule config.

post

Update a schedule config item.

Update a schedule config item.

Body

Media type: application/json

Type: object

HTTP status code 200

The config is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get post

Replication configuration.

get

Get replication config.

post

Update a replication config item.

Update a replication config item.

Body

Media type: application/json

Type: object

HTTP status code 200

The config is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get post

The label property configuration.

get

Get label property config.

post

Update label property config item.

Update label property config item.

Body

Media type: application/json

Type: object

Properties
  • action: required (one of set, delete)
  • type: required (reject-leader)
  • label-key: required (string)
  • label-value: required (string)

HTTP status code 200

The config is updated.

HTTP status code 500

PD server failed to proceed the request.

/stores

The stores in the cluster.

get

get

Get stores in the cluster.

get post

The balance rate limit for all stores.

get

Get all stores' balance rate limit.

post

Set all stores' balance rate limit.

Set all stores' balance rate limit.

Body

Media type: application/json

Type: object

HTTP status code 200

All stores' balance rate limits are updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

delete

Remove all tombstone stores.

delete

Remove all tombstone stores.

/store/{storeId}

A specific store.

get delete

get

Get a store's information.

delete

Take down a store from the cluster.

Get a store's information.

URI Parameters

  • storeId: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • store: required (object)
    • id: required (integer)
    • address: required (string)
    • state: required (one of 0, 1, 2)
    • state_name: required (one of Up, Disconnected, Down, Offline, Tombstone)
    • labels: (array of StoreLabel)

      Items: StoreLabel

      • key: required (string)
      • value: required (string)
    • version: (string)
    • peer_address: required (string)
  • status: required (object)
    • capacity: required (string)
    • available: required (string)
    • used_size: required (string)
    • leader_count: (integer)
    • leader_weight: (number)
    • leader_score: (number)
    • leader_size: (integer)
    • region_count: (integer)
    • region_weight: (number)
    • region_score: (number)
    • region_size: (integer)
    • sending_snap_count: (integer)
    • receiving_snap_count: (integer)
    • applying_snap_count: (integer)
    • is_busy: (boolean)
    • start_ts: (string)
    • last_heartbeat_ts: (string)
    • uptime: (string)

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

Take down a store from the cluster.

URI Parameters

  • storeId: required (integer)

Query Parameters

  • force: (string)

    Set status to Tombstone directly.

HTTP status code 200

The store is set as Offline or Tombstone.

HTTP status code 400

The input is invalid.

HTTP status code 404

The store does not exist.

HTTP status code 410

The store has already been removed.

HTTP status code 500

PD server failed to proceed the request.

post

The state for the specific store.

post

Set the store's state.

Set the store's state.

URI Parameters

  • storeId: required (integer)

Query Parameters

  • state: required (one of Up, Offline, Tombstone)

HTTP status code 200

The store's state is updated.

HTTP status code 400

The input is invalid.

HTTP status code 404

The store does not exist.

HTTP status code 500

PD server failed to proceed the request.

post

The label for the specific store.

post

Set the store's label.

Set the store's label.

URI Parameters

  • storeId: required (integer)

Body

Media type: application/json

Type: object

HTTP status code 200

The store's label is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

post

The weight for the specific store.

post

Set the store's leader/region weight.

Set the store's leader/region weight.

URI Parameters

  • storeId: required (integer)

Body

Media type: application/json

Type: object

HTTP status code 200

The store's weight is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

post

The balance rate limit for the specific store.

post

Set the store's balance rate limit.

Set the store's balance rate limit.

URI Parameters

  • storeId: required (integer)

Body

Media type: application/json

Type: object

HTTP status code 200

The store's balance rate limit is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/labels

The store label values in the cluster.

get

get

List all label values.

get

get

List stores that have specific label values.

/region

A specific region in the cluster.

get

get

Search for a region by region ID.

Search for a region by region ID.

URI Parameters

  • id: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • id: required (integer)
  • start_key: required (string)
  • end_key: required (string)
  • epoch: (object)
    • conf_ver: (integer)
    • version: (integer)
  • peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • leader: (object)
    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • down_peers: (array of PeerStats)

    Items: PeerStats

    • peer: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_seconds: required (integer)
  • pending_peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • written_bytes: (integer)
  • read_bytes: (integer)
  • approximate_size: (integer)
  • approximate_keys: (integer)

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get

get

Search for a region by a key.

Search for a region by a key.

URI Parameters

  • key: required (string)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • id: required (integer)
  • start_key: required (string)
  • end_key: required (string)
  • epoch: (object)
    • conf_ver: (integer)
    • version: (integer)
  • peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • leader: (object)
    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • down_peers: (array of PeerStats)

    Items: PeerStats

    • peer: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_seconds: required (integer)
  • pending_peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • written_bytes: (integer)
  • read_bytes: (integer)
  • approximate_size: (integer)
  • approximate_keys: (integer)

HTTP status code 500

PD server failed to proceed the request.

/regions

The regions in the cluster.

get

get

List all regions in the cluster.

get

get

Get region count in the cluster.

get

get

List regions with the highest write flow.

get

get

List regions with the highest read flow.

get

get

List regions with the largest conf version.

get

get

List regions with the largest version.

get

get

List regions with the largest size.

get

get

List regions start from a key.

get

get

List regions with unhealthy status.

List regions with unhealthy status.

URI Parameters

  • filter: required (one of miss-peer, extra-peer, pending-peer, down-peer, incorrect-ns, offline-peer, empty-region)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • count: required (integer)
  • regions: required (array of Region)

    Items: Region

    • id: required (integer)
    • start_key: required (string)
    • end_key: required (string)
    • epoch: (object)
      • conf_ver: (integer)
      • version: (integer)
    • peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • leader: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_peers: (array of PeerStats)

      Items: PeerStats

      • peer: (object)
        • id: required (integer)
        • store_id: required (integer)
        • is_learner: (boolean)
      • down_seconds: required (integer)
    • pending_peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • written_bytes: (integer)
    • read_bytes: (integer)
    • approximate_size: (integer)
    • approximate_keys: (integer)

HTTP status code 500

PD server failed to proceed the request.

get

get

List sibling regions of a specific region.

List sibling regions of a specific region.

URI Parameters

  • id: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • count: required (integer)
  • regions: required (array of Region)

    Items: Region

    • id: required (integer)
    • start_key: required (string)
    • end_key: required (string)
    • epoch: (object)
      • conf_ver: (integer)
      • version: (integer)
    • peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • leader: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_peers: (array of PeerStats)

      Items: PeerStats

      • peer: (object)
        • id: required (integer)
        • store_id: required (integer)
        • is_learner: (boolean)
      • down_seconds: required (integer)
    • pending_peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • written_bytes: (integer)
    • read_bytes: (integer)
    • approximate_size: (integer)
    • approximate_keys: (integer)

HTTP status code 400

The input is invalid.

HTTP status code 404

The region does not exist.

HTTP status code 500

PD server failed to proceed the request.

get

get

List all regions of a specific store.

List all regions of a specific store.

URI Parameters

  • id: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • count: required (integer)
  • regions: required (array of Region)

    Items: Region

    • id: required (integer)
    • start_key: required (string)
    • end_key: required (string)
    • epoch: (object)
      • conf_ver: (integer)
      • version: (integer)
    • peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • leader: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_peers: (array of PeerStats)

      Items: PeerStats

      • peer: (object)
        • id: required (integer)
        • store_id: required (integer)
        • is_learner: (boolean)
      • down_seconds: required (integer)
    • pending_peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • written_bytes: (integer)
    • read_bytes: (integer)
    • approximate_size: (integer)
    • approximate_keys: (integer)

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/schedulers

Running schedulers.

get post

get

List running schedulers.

post

Create a scheduler.

Create a scheduler.

Body

Media type: application/json

Type: object

Properties
  • name: required (string)

HTTP status code 200

The scheduler is created.

HTTP status code 400

Bad format request.

HTTP status code 500

PD server failed to proceed the request.

delete

A specific scheduler.

delete

Delete a scheduler.

Delete a scheduler.

URI Parameters

  • name: required (string)

    The name of the scheduler.

HTTP status code 200

The scheduler is removed.

HTTP status code 500

PD server failed to proceed the request.

/operators

Pending operators.

get post

get

List pending operators.

post

Create an operator.

Create an operator.

Body

Media type: application/json

Type: object

Properties
  • name: required (string)

HTTP status code 200

The operator is created.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get delete

A specific Region's pending operator.

get

Get a Region's pending operator.

delete

Cancel a Region's pending operator.

Get a Region's pending operator.

URI Parameters

  • regionId: required (integer)

    A Region's Id.

HTTP status code 200

Body

Media type: application/json

Type: string

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

Cancel a Region's pending operator.

URI Parameters

  • regionId: required (integer)

    A Region's Id.

HTTP status code 200

The pending operator is cancelled.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/hotspot

The hot spots status in the cluster.

get

get

List the hot write regions.

get

get

List the hot read regions.

get

get

List the hot stores.

/stats

Statistics of the cluster.

get

get

Get region statistics of a specified range.

/trend

Trend of data growth and movements.

get

get

Get the growth and changes of data in the most recent period of time.

/admin

delete

delete

Drop a specific region from cache.

Drop a specific region from cache.

URI Parameters

  • id: required (integer)

HTTP status code 200

The region is removed from server cache.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

post

The log level of PD server.

post

Set log level.

Set log level.

Body

Media type: application/json

Type: string

HTTP status code 200

The log level is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

\ No newline at end of file +

Placement Driver API API documentation version v1

http://{pdAddr}/pd/api/{version}

  • pdAddr: required (string)

    The PD server address, formatted as 'host:port'.

  • version: required (v1)

/cluster/status

Cluster status.

get

get

Get cluster status.

/version

The version of PD server.

get

get

Get the version of PD server.

/status

The build info of PD server.

get

get

Get the build info of PD server.

/diagnose

Diagnostic information of the cluster.

get

get

/members

The PD servers in the cluster.

get

get

List all PD servers in the cluster.

delete post

A specific PD server.

delete

Remove a PD server from the cluster.

post

Set leader priority of a PD member.

Remove a PD server from the cluster.

URI Parameters

  • name: required (string)

HTTP status code 200

The PD server is successfully removed.

HTTP status code 400

The input is invalid.

HTTP status code 404

The member does not exist.

HTTP status code 500

PD server failed to proceed the request.

Set leader priority of a PD member.

URI Parameters

  • name: required (string)

Body

Media type: application/json

Type: object

Properties
  • leader-priority: required (integer)

HTTP status code 200

The leader priority is updated.

HTTP status code 400

The input is invalid.

HTTP status code 404

The member does not exist.

HTTP status code 500

PD server failed to proceed the request.

delete

A specific PD server.

delete

Remove a PD server from the cluster.

Remove a PD server from the cluster.

URI Parameters

  • id: required (integer)

HTTP status code 200

The PD server is successfully removed.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/leader

The leader PD server of the cluster.

get

get

Get the leader PD server of the cluster.

post

post

Transfer leadership to another PD server.

Transfer leadership to another PD server.

HTTP status code 200

The transfer command is submitted.

HTTP status code 500

PD server failed to proceed the request.

post

post

Transfer leadership to the specific PD server.

Transfer leadership to the specific PD server.

URI Parameters

  • nextLeader: required (string)

HTTP status code 200

The transfer command is submitted.

HTTP status code 500

PD server failed to proceed the request.

/health

Health status of PD servers.

get

get

/config

PD cluster configuration.

get post

get

Get full config.

post

Update a config item.

Update a config item.

Body

Media type: application/json

Type: object

HTTP status code 200

The config is updated.

HTTP status code 500

PD server failed to proceed the request.

get post

Schedule configuration.

get

Get schedule config.

post

Update a schedule config item.

Update a schedule config item.

Body

Media type: application/json

Type: object

HTTP status code 200

The config is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get post

Replication configuration.

get

Get replication config.

post

Update a replication config item.

Update a replication config item.

Body

Media type: application/json

Type: object

HTTP status code 200

The config is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get post

The label property configuration.

get

Get label property config.

post

Update label property config item.

Update label property config item.

Body

Media type: application/json

Type: object

Properties
  • action: required (one of set, delete)
  • type: required (reject-leader)
  • label-key: required (string)
  • label-value: required (string)

HTTP status code 200

The config is updated.

HTTP status code 500

PD server failed to proceed the request.

get

Placement rules.

get

Get all placement rules.

get

Placement rules of a group.

get

Get placement rules of a group.

Get placement rules of a group.

URI Parameters

  • group: required (string)

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: Rule

  • group_id: required (string)
  • id: required (string)
  • index: (integer)
  • override: (boolean)
  • start_key: required (string)
  • end_key: required (string)
  • role: required (one of voter, leader, follower, learner)
  • count: required (integer - minimum: 1)
  • label_constraints: required (array of LabelConstraint)

    Items: LabelConstraint

    • key: required (string)
    • op: required (one of in, notIn, exists, notExists)
    • values: (array of string)
  • location_labels: required (array of string)

HTTP status code 412

Placement rules feature is not enabled.

HTTP status code 500

PD server failed to proceed the request.

get

Placement rules matched by a region.

get

Get placement rules matched by a region.

Get placement rules matched by a region.

URI Parameters

  • region: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: Rule

  • group_id: required (string)
  • id: required (string)
  • index: (integer)
  • override: (boolean)
  • start_key: required (string)
  • end_key: required (string)
  • role: required (one of voter, leader, follower, learner)
  • count: required (integer - minimum: 1)
  • label_constraints: required (array of LabelConstraint)

    Items: LabelConstraint

    • key: required (string)
    • op: required (one of in, notIn, exists, notExists)
    • values: (array of string)
  • location_labels: required (array of string)

HTTP status code 400

The region ID is invalid.

HTTP status code 404

The region is not found.

HTTP status code 500

PD server failed to proceed the request.

get

Placement rules matched by a key.

get

Get placement rules matched by a key.

Get placement rules matched by a key.

URI Parameters

  • key: required (string)

HTTP status code 200

Body

Media type: application/json

Type: array of object

Items: Rule

  • group_id: required (string)
  • id: required (string)
  • index: (integer)
  • override: (boolean)
  • start_key: required (string)
  • end_key: required (string)
  • role: required (one of voter, leader, follower, learner)
  • count: required (integer - minimum: 1)
  • label_constraints: required (array of LabelConstraint)

    Items: LabelConstraint

    • key: required (string)
    • op: required (one of in, notIn, exists, notExists)
    • values: (array of string)
  • location_labels: required (array of string)

HTTP status code 400

The key is not in hex format.

HTTP status code 412

Placement rules feature is not enabled.

HTTP status code 500

PD server failed to proceed the request.

get delete

A Placement Rule.

get

Get a single Placement Rule.

delete

Delete a Placement Rule.

Get a single Placement Rule.

URI Parameters

  • group: required (string)
  • id: required (string)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • group_id: required (string)
  • id: required (string)
  • index: (integer)
  • override: (boolean)
  • start_key: required (string)
  • end_key: required (string)
  • role: required (one of voter, leader, follower, learner)
  • count: required (integer - minimum: 1)
  • label_constraints: required (array of LabelConstraint)

    Items: LabelConstraint

    • key: required (string)
    • op: required (one of in, notIn, exists, notExists)
    • values: (array of string)
  • location_labels: required (array of string)

HTTP status code 404

The Rule is not found.

HTTP status code 412

Placement rules feature is not enabled.

HTTP status code 500

PD server failed to proceed the request.

Delete a Placement Rule.

URI Parameters

  • group: required (string)
  • id: required (string)

HTTP status code 200

The Rule is delete.

HTTP status code 412

Placement rules feature is not enabled.

HTTP status code 500

PD server failed to proceed the request.

post

A Placement Rule.

post

Add or update a Placement rule.

Add or update a Placement rule.

Body

Media type: application/json

Type: object

Properties
  • group_id: required (string)
  • id: required (string)
  • index: (integer)
  • override: (boolean)
  • start_key: required (string)
  • end_key: required (string)
  • role: required (one of voter, leader, follower, learner)
  • count: required (integer - minimum: 1)
  • label_constraints: required (array of LabelConstraint)

    Items: LabelConstraint

    • key: required (string)
    • op: required (one of in, notIn, exists, notExists)
    • values: (array of string)
  • location_labels: required (array of string)

HTTP status code 200

The rule is created or updated.

HTTP status code 400

The input is invalid.

HTTP status code 412

Placement rules feature is not enabled.

HTTP status code 500

PD server failed to proceed the request.

/stores

The stores in the cluster.

get

get

Get stores in the cluster.

get post

The balance rate limit for all stores.

get

Get all stores' balance rate limit.

post

Set all stores' balance rate limit.

Set all stores' balance rate limit.

Body

Media type: application/json

Type: object

HTTP status code 200

All stores' balance rate limits are updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

delete

Remove all tombstone stores.

delete

Remove all tombstone stores.

/store/{storeId}

A specific store.

get delete

get

Get a store's information.

delete

Take down a store from the cluster.

Get a store's information.

URI Parameters

  • storeId: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • store: required (object)
    • id: required (integer)
    • address: required (string)
    • state: required (one of 0, 1, 2)
    • state_name: required (one of Up, Disconnected, Down, Offline, Tombstone)
    • labels: (array of StoreLabel)

      Items: StoreLabel

      • key: required (string)
      • value: required (string)
    • version: (string)
    • peer_address: required (string)
  • status: required (object)
    • capacity: required (string)
    • available: required (string)
    • used_size: required (string)
    • leader_count: (integer)
    • leader_weight: (number)
    • leader_score: (number)
    • leader_size: (integer)
    • region_count: (integer)
    • region_weight: (number)
    • region_score: (number)
    • region_size: (integer)
    • sending_snap_count: (integer)
    • receiving_snap_count: (integer)
    • applying_snap_count: (integer)
    • is_busy: (boolean)
    • start_ts: (string)
    • last_heartbeat_ts: (string)
    • uptime: (string)

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

Take down a store from the cluster.

URI Parameters

  • storeId: required (integer)

Query Parameters

  • force: (string)

    Set status to Tombstone directly.

HTTP status code 200

The store is set as Offline or Tombstone.

HTTP status code 400

The input is invalid.

HTTP status code 404

The store does not exist.

HTTP status code 410

The store has already been removed.

HTTP status code 500

PD server failed to proceed the request.

post

The state for the specific store.

post

Set the store's state.

Set the store's state.

URI Parameters

  • storeId: required (integer)

Query Parameters

  • state: required (one of Up, Offline, Tombstone)

HTTP status code 200

The store's state is updated.

HTTP status code 400

The input is invalid.

HTTP status code 404

The store does not exist.

HTTP status code 500

PD server failed to proceed the request.

post

The label for the specific store.

post

Set the store's label.

Set the store's label.

URI Parameters

  • storeId: required (integer)

Body

Media type: application/json

Type: object

HTTP status code 200

The store's label is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

post

The weight for the specific store.

post

Set the store's leader/region weight.

Set the store's leader/region weight.

URI Parameters

  • storeId: required (integer)

Body

Media type: application/json

Type: object

HTTP status code 200

The store's weight is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

post

The balance rate limit for the specific store.

post

Set the store's balance rate limit.

Set the store's balance rate limit.

URI Parameters

  • storeId: required (integer)

Body

Media type: application/json

Type: object

HTTP status code 200

The store's balance rate limit is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/labels

The store label values in the cluster.

get

get

List all label values.

get

get

List stores that have specific label values.

/region

A specific region in the cluster.

get

get

Search for a region by region ID.

Search for a region by region ID.

URI Parameters

  • id: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • id: required (integer)
  • start_key: required (string)
  • end_key: required (string)
  • epoch: (object)
    • conf_ver: (integer)
    • version: (integer)
  • peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • leader: (object)
    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • down_peers: (array of PeerStats)

    Items: PeerStats

    • peer: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_seconds: required (integer)
  • pending_peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • written_bytes: (integer)
  • read_bytes: (integer)
  • approximate_size: (integer)
  • approximate_keys: (integer)

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get

get

Search for a region by a key.

Search for a region by a key.

URI Parameters

  • key: required (string)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • id: required (integer)
  • start_key: required (string)
  • end_key: required (string)
  • epoch: (object)
    • conf_ver: (integer)
    • version: (integer)
  • peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • leader: (object)
    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • down_peers: (array of PeerStats)

    Items: PeerStats

    • peer: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_seconds: required (integer)
  • pending_peers: (array of Peer)

    Items: Peer

    • id: required (integer)
    • store_id: required (integer)
    • is_learner: (boolean)
  • written_bytes: (integer)
  • read_bytes: (integer)
  • approximate_size: (integer)
  • approximate_keys: (integer)

HTTP status code 500

PD server failed to proceed the request.

/regions

The regions in the cluster.

get

get

List all regions in the cluster.

get

get

Get region count in the cluster.

get

get

List regions with the highest write flow.

get

get

List regions with the highest read flow.

get

get

List regions with the largest conf version.

get

get

List regions with the largest version.

get

get

List regions with the largest size.

get

get

List regions start from a key.

get

get

List regions with unhealthy status.

List regions with unhealthy status.

URI Parameters

  • filter: required (one of miss-peer, extra-peer, pending-peer, down-peer, incorrect-ns, offline-peer, empty-region)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • count: required (integer)
  • regions: required (array of Region)

    Items: Region

    • id: required (integer)
    • start_key: required (string)
    • end_key: required (string)
    • epoch: (object)
      • conf_ver: (integer)
      • version: (integer)
    • peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • leader: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_peers: (array of PeerStats)

      Items: PeerStats

      • peer: (object)
        • id: required (integer)
        • store_id: required (integer)
        • is_learner: (boolean)
      • down_seconds: required (integer)
    • pending_peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • written_bytes: (integer)
    • read_bytes: (integer)
    • approximate_size: (integer)
    • approximate_keys: (integer)

HTTP status code 500

PD server failed to proceed the request.

get

get

List sibling regions of a specific region.

List sibling regions of a specific region.

URI Parameters

  • id: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • count: required (integer)
  • regions: required (array of Region)

    Items: Region

    • id: required (integer)
    • start_key: required (string)
    • end_key: required (string)
    • epoch: (object)
      • conf_ver: (integer)
      • version: (integer)
    • peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • leader: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_peers: (array of PeerStats)

      Items: PeerStats

      • peer: (object)
        • id: required (integer)
        • store_id: required (integer)
        • is_learner: (boolean)
      • down_seconds: required (integer)
    • pending_peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • written_bytes: (integer)
    • read_bytes: (integer)
    • approximate_size: (integer)
    • approximate_keys: (integer)

HTTP status code 400

The input is invalid.

HTTP status code 404

The region does not exist.

HTTP status code 500

PD server failed to proceed the request.

get

get

List all regions of a specific store.

List all regions of a specific store.

URI Parameters

  • id: required (integer)

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • count: required (integer)
  • regions: required (array of Region)

    Items: Region

    • id: required (integer)
    • start_key: required (string)
    • end_key: required (string)
    • epoch: (object)
      • conf_ver: (integer)
      • version: (integer)
    • peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • leader: (object)
      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • down_peers: (array of PeerStats)

      Items: PeerStats

      • peer: (object)
        • id: required (integer)
        • store_id: required (integer)
        • is_learner: (boolean)
      • down_seconds: required (integer)
    • pending_peers: (array of Peer)

      Items: Peer

      • id: required (integer)
      • store_id: required (integer)
      • is_learner: (boolean)
    • written_bytes: (integer)
    • read_bytes: (integer)
    • approximate_size: (integer)
    • approximate_keys: (integer)

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/schedulers

Running schedulers.

get post

get

List running schedulers.

post

Create a scheduler.

Create a scheduler.

Body

Media type: application/json

Type: object

Properties
  • name: required (string)

HTTP status code 200

The scheduler is created.

HTTP status code 400

Bad format request.

HTTP status code 500

PD server failed to proceed the request.

delete

A specific scheduler.

delete

Delete a scheduler.

Delete a scheduler.

URI Parameters

  • name: required (string)

    The name of the scheduler.

HTTP status code 200

The scheduler is removed.

HTTP status code 500

PD server failed to proceed the request.

/operators

Pending operators.

get post

get

List pending operators.

post

Create an operator.

Create an operator.

Body

Media type: application/json

Type: object

Properties
  • name: required (string)

HTTP status code 200

The operator is created.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

get delete

A specific Region's pending operator.

get

Get a Region's pending operator.

delete

Cancel a Region's pending operator.

Get a Region's pending operator.

URI Parameters

  • regionId: required (integer)

    A Region's Id.

HTTP status code 200

Body

Media type: application/json

Type: string

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

Cancel a Region's pending operator.

URI Parameters

  • regionId: required (integer)

    A Region's Id.

HTTP status code 200

The pending operator is cancelled.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

/hotspot

The hot spots status in the cluster.

get

get

List the hot write regions.

get

get

List the hot read regions.

get

get

List the hot stores.

/stats

Statistics of the cluster.

get

get

Get region statistics of a specified range.

/trend

Trend of data growth and movements.

get

get

Get the growth and changes of data in the most recent period of time.

/admin

delete

delete

Drop a specific region from cache.

Drop a specific region from cache.

URI Parameters

  • id: required (integer)

HTTP status code 200

The region is removed from server cache.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

post

The log level of PD server.

post

Set log level.

Set log level.

Body

Media type: application/json

Type: string

HTTP status code 200

The log level is updated.

HTTP status code 400

The input is invalid.

HTTP status code 500

PD server failed to proceed the request.

\ No newline at end of file diff --git a/server/api/api.raml b/server/api/api.raml index 5a3ba7159b4..0ae99d721d2 100644 --- a/server/api/api.raml +++ b/server/api/api.raml @@ -374,6 +374,32 @@ types: type: string enum: [ leader, region ] count: integer + + Rule: + type: object + properties: + group_id: string + id: string + index?: integer + override?: boolean + start_key: string + end_key: string + role: + type: string + enum: [voter, leader, follower, learner] + count: + type: integer + minimum: 1 + label_constraints: LabelConstraint[] + location_labels: string[] + LabelConstraint: + type: object + properties: + key: string + op: + type: string + enum: [ in, notIn, exists, notExists ] + values?: string[] /cluster/status: description: Cluster status. @@ -608,7 +634,113 @@ types: description: The config is updated. 500: description: PD server failed to proceed the request. - + /rules: + description: Placement rules. + get: + description: Get all placement rules. + responses: + 200: + body: + application/json: + type: Rule[] + 412: + description: Placement rules feature is not enabled. + 500: + description: PD server failed to proceed the request. + /rules/group/{group}: + description: Placement rules of a group. + uriParameters: + group: string + get: + description: Get placement rules of a group. + responses: + 200: + body: + application/json: + type: Rule[] + 412: + description: Placement rules feature is not enabled. + 500: + description: PD server failed to proceed the request. + /rules/region/{region}: + description: Placement rules matched by a region. + uriParameters: + region: integer + get: + description: Get placement rules matched by a region. + responses: + 200: + body: + application/json: + type: Rule[] + 400: + description: The region ID is invalid. + 404: + description: The region is not found. + 500: + description: PD server failed to proceed the request. + /rules/key/{key}: + description: Placement rules matched by a key. + uriParameters: + key: string + get: + description: Get placement rules matched by a key. + responses: + 200: + body: + application/json: + type: Rule[] + 400: + description: The key is not in hex format. + 412: + description: Placement rules feature is not enabled. + 500: + description: PD server failed to proceed the request. + /rule/{group}/{id}: + description: A Placement Rule. + uriParameters: + group: string + id: string + get: + description: Get a single Placement Rule. + responses: + 200: + body: + application/json: + type: Rule + 404: + description: The Rule is not found. + 412: + description: Placement rules feature is not enabled. + 500: + description: PD server failed to proceed the request. + delete: + description: Delete a Placement Rule. + responses: + 200: + description: The Rule is delete. + 412: + description: Placement rules feature is not enabled. + 500: + description: PD server failed to proceed the request. + /rule: + description: A Placement Rule. + post: + description: Add or update a Placement rule. + body: + application/json: + description: Placement Rule. + type: Rule + responses: + 200: + description: The rule is created or updated. + 400: + description: The input is invalid. + 412: + description: Placement rules feature is not enabled. + 500: + description: PD server failed to proceed the request. + /stores: description: The stores in the cluster. get: diff --git a/server/api/router.go b/server/api/router.go index 94186a2402d..2704e2c1e0c 100644 --- a/server/api/router.go +++ b/server/api/router.go @@ -60,6 +60,15 @@ func createRouter(prefix string, svr *server.Server) *mux.Router { router.HandleFunc("/api/v1/config/cluster-version", confHandler.GetClusterVersion).Methods("GET") router.HandleFunc("/api/v1/config/cluster-version", confHandler.SetClusterVersion).Methods("POST") + rulesHandler := newRulesHandler(svr, rd) + router.HandleFunc("/api/v1/config/rules", rulesHandler.GetAll).Methods("GET") + router.HandleFunc("/api/v1/config/rules/group/{group}", rulesHandler.GetAllByGroup).Methods("GET") + router.HandleFunc("/api/v1/config/rules/region/{region}", rulesHandler.GetAllByRegion).Methods("GET") + router.HandleFunc("/api/v1/config/rules/key/{key}", rulesHandler.GetAllByKey).Methods("GET") + router.HandleFunc("/api/v1/config/rule/{group}/{id}", rulesHandler.Get).Methods("GET") + router.HandleFunc("/api/v1/config/rule", rulesHandler.Set).Methods("POST") + router.HandleFunc("/api/v1/config/rule/{group}/{id}", rulesHandler.Delete).Methods("DELETE") + storeHandler := newStoreHandler(handler, rd) router.HandleFunc("/api/v1/store/{id}", storeHandler.Get).Methods("GET") router.HandleFunc("/api/v1/store/{id}", storeHandler.Delete).Methods("DELETE") diff --git a/server/api/rule.go b/server/api/rule.go new file mode 100644 index 00000000000..d4c4c67ecc5 --- /dev/null +++ b/server/api/rule.go @@ -0,0 +1,210 @@ +// Copyright 2019 PingCAP, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// See the License for the specific language governing permissions and +// limitations under the License. + +package api + +import ( + "bytes" + "encoding/hex" + "net/http" + "strconv" + + "github.com/gorilla/mux" + "github.com/pingcap/pd/pkg/apiutil" + "github.com/pingcap/pd/pkg/codec" + "github.com/pingcap/pd/server" + "github.com/pingcap/pd/server/core" + "github.com/pingcap/pd/server/schedule/placement" + "github.com/pkg/errors" + "github.com/unrolled/render" +) + +var errPlacementDisabled = errors.New("placement rules feature is disabled") + +type ruleHandler struct { + svr *server.Server + rd *render.Render +} + +func newRulesHandler(svr *server.Server, rd *render.Render) *ruleHandler { + return &ruleHandler{ + svr: svr, + rd: rd, + } +} + +func (h *ruleHandler) GetAll(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + rules := cluster.GetRuleManager().GetAllRules() + h.rd.JSON(w, http.StatusOK, rules) +} + +func (h *ruleHandler) GetAllByGroup(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + group := mux.Vars(r)["group"] + rules := cluster.GetRuleManager().GetRulesByGroup(group) + h.rd.JSON(w, http.StatusOK, rules) +} + +func (h *ruleHandler) GetAllByRegion(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + regionStr := mux.Vars(r)["region"] + regionID, err := strconv.ParseUint(regionStr, 10, 64) + if err != nil { + h.rd.JSON(w, http.StatusBadRequest, "invalid region id") + return + } + region := cluster.GetRegion(regionID) + if region == nil { + h.rd.JSON(w, http.StatusNotFound, server.ErrRegionNotFound(regionID).Error()) + return + } + rules := cluster.GetRuleManager().GetRulesForApplyRegion(region) + h.rd.JSON(w, http.StatusOK, rules) +} + +func (h *ruleHandler) GetAllByKey(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + keyHex := mux.Vars(r)["key"] + key, err := hex.DecodeString(keyHex) + if err != nil { + h.rd.JSON(w, http.StatusBadRequest, "key should be in hex format") + return + } + rules := cluster.GetRuleManager().GetRulesByKey(key) + h.rd.JSON(w, http.StatusOK, rules) +} + +func (h *ruleHandler) Get(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + group, id := mux.Vars(r)["group"], mux.Vars(r)["id"] + rule := cluster.GetRuleManager().GetRule(group, id) + if rule == nil { + h.rd.JSON(w, http.StatusNotFound, nil) + return + } + h.rd.JSON(w, http.StatusOK, rule) +} + +func (h *ruleHandler) Set(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + var rule placement.Rule + if err := apiutil.ReadJSONRespondError(h.rd, w, r.Body, &rule); err != nil { + return + } + if err := h.checkRule(&rule); err != nil { + h.rd.JSON(w, http.StatusBadRequest, err.Error()) + return + } + if err := cluster.GetRuleManager().SetRule(&rule); err != nil { + h.rd.JSON(w, http.StatusInternalServerError, err.Error()) + return + } + h.rd.JSON(w, http.StatusOK, nil) +} + +func (h *ruleHandler) checkRule(r *placement.Rule) error { + start, err := hex.DecodeString(r.StartKeyHex) + if err != nil { + return errors.Wrap(err, "start key is not in hex format") + } + end, err := hex.DecodeString(r.EndKeyHex) + if err != nil { + return errors.Wrap(err, "end key is not hex format") + } + if len(start) > 0 && bytes.Compare(end, start) <= 0 { + return errors.New("endKey should be greater than startKey") + } + + keyType := h.svr.GetConfig().PDServerCfg.KeyType + if keyType == core.Table.String() || keyType == core.Txn.String() { + if len(start) > 0 { + if _, _, err = codec.DecodeBytes(start); err != nil { + return errors.Wrapf(err, "start key should be encoded in %s mode", keyType) + } + } + if len(end) > 0 { + if _, _, err = codec.DecodeBytes(end); err != nil { + return errors.Wrapf(err, "end key should be encoded in %s mode", keyType) + } + } + } + + return nil +} + +func (h *ruleHandler) Delete(w http.ResponseWriter, r *http.Request) { + cluster := h.svr.GetRaftCluster() + if cluster == nil { + h.rd.JSON(w, http.StatusInternalServerError, server.ErrNotBootstrapped.Error()) + return + } + if !cluster.IsPlacementRulesEnabled() { + h.rd.JSON(w, http.StatusPreconditionFailed, errPlacementDisabled.Error()) + return + } + group, id := mux.Vars(r)["group"], mux.Vars(r)["id"] + if err := cluster.GetRuleManager().DeleteRule(group, id); err != nil { + h.rd.JSON(w, http.StatusInternalServerError, err.Error()) + return + } + h.rd.JSON(w, http.StatusOK, nil) +}