From 6d3b21e6905de7a585bde33639c96edede394262 Mon Sep 17 00:00:00 2001 From: Ryan Leung Date: Wed, 2 Mar 2022 14:56:28 +0800 Subject: [PATCH 1/3] introduce HTTP API V2 in PD Signed-off-by: Ryan Leung --- text/0084-pd-http-api-v2.md | 72 +++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 text/0084-pd-http-api-v2.md diff --git a/text/0084-pd-http-api-v2.md b/text/0084-pd-http-api-v2.md new file mode 100644 index 00000000..9f04995e --- /dev/null +++ b/text/0084-pd-http-api-v2.md @@ -0,0 +1,72 @@ +# PD HTTP API V2 + +## Motivation + +The V2 API aims to provide a standard RESTful API for PD. The current HTTP API doesn't follow the RESTful API conventions. We have summarized some problems of the current status: + +- mixed-use of `_` and `-` in the path +- some methods are not accurate, e.g., we do not distinguish between PUT and POST +- the resource should use a noun +- query parameter should not occur in the path +- mixed-use of singular and plural nouns + +Besides the above problems, we are going to refine some internal structures and reduce some unnecessary APIs which are never been used before. + +## Detailed Design + +We can use gin as our HTTP web framework in the V2 API, which is more popular and has a better ecosystem. + +Here is a basic example for stores: + +```go +router := gin.New() +router.Use(middlewares.Redirector()) +root := router.Group(apiV2Prefix) +meta := root.Group("meta") +meta.Use(middlewares.BootstrapChecker()) +meta.GET("/stores", handlers.GetStores()) +meta.GET("/stores/:id", handlers.GetStoreByID()) +meta.DELETE("/stores/:id", handlers.DeleteStoreByID()) +meta.PATCH("/stores/:id", handlers.UpdateStoreByID()) +``` + +### Middleware + +We can easily add the middleware through the `Use` function and the middleware we defined only needs to return [gin.HandlerFunc](https://github.com/gin-gonic/gin/blob/v1.7.7/gin.go#L34). This also can be applied in a specified API group. Gin has provided many [ready-made middleware](https://github.com/gin-contrib) which is convenient. + +### Path definition + +#### Resource + +Since the key abstraction of information in RESTful API is a resource, it can be any non-virtual object. We use plural form to represent a set of objects, e.g., `/pd/api/v2/stores` and use the plural form with a unique field to represent a singular object, e.g., `/pd/api/v2/stores/:id`. There should not be a verb or any query parameter existing in the path. The previous path like `/pd/api/v1/store/{id}/state` should be rewritten to `/pd/api/v2/stores/:id` with `state` data in JSON format as an input. + +#### Method + +Here is a simple guide about how to use choose the correct method: + +- GET: retrieve resources only +- POST: create resources or do a custom action. We should avoid using it on a single resource for a creating purpose. +- PUT: replace resources or collections +- PATCH: make a partial update on a resource +- DELETE: delete the resources + +#### Word delimiter + +The hyphen will be recommended to use as the word delimiter. + +#### Group + +For those middlewares that only need to be applied in a set of APIs, we can use API group. API group also can be used to divide our APIs into different sets according to their purpose and share the same middleware. The previous `/pd/api/v1/admin/*` can be put into `admin` group. For stores itself, we can put them into `meta` group, so the previous `/pd/api/v1/stores` or `/pd/api/v1/store` become to `/pd/api/v2/meta/stores`. Currently, the V1 API can be divided into the following groups: + +- member: something about etcd itself +- meta: those resources related to PD meta info, the entity in PD core package, like regions, stores, cluster +- scheduling: use to control the scheduling behaviors, e.g., schedulers, checkers, operators +- admin: control the system behavior, e.g., log, ping +- debug: debug information through go pprof +- extension: some extra features required by other components + +There are some other APIs that don't belong to any group mentioned above. We can decide to use an individual group according to middleware usage. + +#### Custom action + +We have many custom actions in API V1, such as `/pd/api/v1/regions/split` or `/pd/api/v1/regions/scatter`, etc. In V2, We recommend using `/pd/api/v2/regions/:action` with `POST` method. There may be [segment conflicts with existing wildcard](https://github.com/gin-gonic/gin/issues/1301) when using gin as the web framework. But fortunately, we don't have this conflict problem after we change existed V1 API to V2. From 710e14f38caf38f694eb19967cadf4ba47981e5c Mon Sep 17 00:00:00 2001 From: Ryan Leung Date: Thu, 3 Mar 2022 11:41:19 +0800 Subject: [PATCH 2/3] add more content Signed-off-by: Ryan Leung --- text/0084-pd-http-api-v2.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/text/0084-pd-http-api-v2.md b/text/0084-pd-http-api-v2.md index 9f04995e..e017acbe 100644 --- a/text/0084-pd-http-api-v2.md +++ b/text/0084-pd-http-api-v2.md @@ -70,3 +70,25 @@ There are some other APIs that don't belong to any group mentioned above. We can #### Custom action We have many custom actions in API V1, such as `/pd/api/v1/regions/split` or `/pd/api/v1/regions/scatter`, etc. In V2, We recommend using `/pd/api/v2/regions/:action` with `POST` method. There may be [segment conflicts with existing wildcard](https://github.com/gin-gonic/gin/issues/1301) when using gin as the web framework. But fortunately, we don't have this conflict problem after we change existed V1 API to V2. + +### Behavior changes + +In V2, we are planning to refactor the original store state. The previous implementation has some drawbacks: + +- the state which is defined between the ProtoBuf and PD has the conflict and only one state can be shown. e.g., a store with a `Down` state can be either `Up` or `Offline` +- the `Offline` is misleading, some users regard it as the `Tombstone` +- there is a lack of a state to describe the online process + +To solve the above problems, the store state is divided into the heartbeat status and the node state. The node state emphasizes the membership status of this store in the cluster. There are 4 states for it: + +- Preparing: represent the online process state, the store in this state more care about the balancing process. +- Serving: the normal state for providing the service +- Removing: just like the original `Offline`, but it's more clear +- Removed: the same as the original `Tombstone` + +As for heartbeat status, we only add one normal status named `Alive` into the previous implementation. + +With these changes, we can do more things like dynamically adjusting scheduling parameters, progress estimation, etc. + +## Compatibility +Once the implementation has been finished, we need to replace the old API with the new version for all components and tools. Also, we should let the user know about this change. The V1 will still leave for some time for compatibility and be deprecated finally. From 7ffecefcb986ff517aa4f30dba5b5558d8d7280d Mon Sep 17 00:00:00 2001 From: Ryan Leung Date: Wed, 18 May 2022 14:10:53 +0800 Subject: [PATCH 3/3] address the comment Signed-off-by: Ryan Leung --- media/node-state-transition.png | Bin 0 -> 41897 bytes text/0084-pd-http-api-v2.md | 15 +++++++++++++++ 2 files changed, 15 insertions(+) create mode 100644 media/node-state-transition.png diff --git a/media/node-state-transition.png b/media/node-state-transition.png new file mode 100644 index 0000000000000000000000000000000000000000..f866f27c4289cbb0e4f4072113ed99b136688e79 GIT binary patch literal 41897 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 literal 0 HcmV?d00001 diff --git a/text/0084-pd-http-api-v2.md b/text/0084-pd-http-api-v2.md index e017acbe..6aab2e98 100644 --- a/text/0084-pd-http-api-v2.md +++ b/text/0084-pd-http-api-v2.md @@ -90,5 +90,20 @@ As for heartbeat status, we only add one normal status named `Alive` into the pr With these changes, we can do more things like dynamically adjusting scheduling parameters, progress estimation, etc. +#### Node state transition + +Here is the newly node state transition graph: + +![node state transition](../media/node-state-transition.png) + +1. When a store is newly added to the cluster, we regard it as `Preparing`. Once it reaches the threshold of its expected region size, it turns into a `Serving` state. +2. When a store in `Serving` state receives the delete store command/HTTP request, it will be changed to `Removing` state. +3. When we don't want to remove the previous store in `Removing` state, we can use the cancel delete command or through HTTP request to change the node state back to `Serving`. +4. When a store is in `Preparing` state, we can also remove it through the delete store command/HTTP request. +5. When a store in `Removing` state has moved all regions on it to the rest stores, it finally becomes `Removed`. + +The threshold of the expected region size in 1 is calculated by accumulating the store region size for each range of the defined placement rules. +For each given range, we first get all rules which involve this range. And for each rule, we get the size of a single replica and then multiply the count defined in the rule to get the expected region size of this rule. Because each placement rule could have different label constraints, so we can obtain the region size weight of a store through the label constraints. Then multiply these two things, we can obtain the store region size of this range. + ## Compatibility Once the implementation has been finished, we need to replace the old API with the new version for all components and tools. Also, we should let the user know about this change. The V1 will still leave for some time for compatibility and be deprecated finally.