Table of Contents |
---|
Problem Statement
Currently, when a developer wants to change the configuration of a cluster, say, create a region (or destroy an index, or update an async event queue) and wants to have the change persisted in the cluster configuration for incoming servers, there is no public API for them to do so. They must replicate the effort of the equivalent gfsh command to achieve the same effect. It would be nice if we can expose what these commands do to a public API.
Product Goals
The developer should be able to:
- Save a configuration to the Cluster Management Service without having to restart the servers
- Obtain the cluster management service from a cache when calling from a client or a server
- Pass a config object to the cluster management service
- Use CRUD operations to manage config objects
- Enable Security Manager with Finer Grain Security
User Goals
Create a more modular product to allow for easy extension and integration.
The beneficiaries of this work are those who want to change the configuration of the cluster (create/destroy regions, indices or gateway receivers/senders etc), and have these changes replicated on all the applicable servers and persisted in the configuration persistence service for new joining servers. This includes developers working on different parts of the code such as Spring Data for Apache, Queries for Lucene index, storage for the JDBC connector, and other Geode developers.
What We Have Now:
Our admin rest API "sort of" already serves this purpose, but it has these shortcomings:
- It's not a public API
- The API is restricted to the operations implemented as gfsh commands, as the argument to the API is a gfsh command string.
- Each command does similar things, yet commands may not be consistent with each other.
Below is a diagram of the current state of things:
Gliffy Diagram | ||||
---|---|---|---|---|
|
From the current state of commands, It's not easy to extract a common interface for all the commands. And developers do not want to use gfsh command strings as a "makeshift" API to call into the command. We are in need of a unified interface and a unified workflow for all the commands.
Proposal
We propose a new Cluster Management Service (CMS) which has two responsibilities:
- Update runtime configuration of servers (if any running)
- Persist configuration (if enabled)
Note that in order to use this API, Cluster Configuration needs to be enabled.
Gliffy Diagram | ||||||
---|---|---|---|---|---|---|
|
The CMS API is exposed as a new endpoint as part of "Admin REST APIs", accepting configuration objects (JSON) that need to be applied to the cluster. CMS adheres to the standard REST semantics, so users can use POST, PATCH, DELETE and GET to create, update, delete or read, respectively. The API returns a JSON body that contains a message describing the result along with standard HTTP status codes.
Root End Point
API | Status Code | Response Body | |||||||
---|---|---|---|---|---|---|---|---|---|
200 |
| ||||||||
401 |
| ||||||||
403 |
|
Create End Point
API | Status Code | Response Body | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Endpoint:http://locator:8080/geode/v2/regions Method: POST Headers: user: user1 password: password1 Body:
| 201 |
| ||||||||||||||
304 |
| |||||||||||||||
400 |
| |||||||||||||||
401 |
| |||||||||||||||
403 |
| |||||||||||||||
500 |
|
Note that the CREATE endpoint is idempotent – i.e. it should be a NOOP if the region already exists.
List End Point
API | Status Code | Response Body | |||||||
---|---|---|---|---|---|---|---|---|---|
200 |
| ||||||||
401 |
| ||||||||
403 |
|
Describe End Point
API | Status Code | Response Body | |||||||
---|---|---|---|---|---|---|---|---|---|
200 |
| ||||||||
401 |
| ||||||||
403 |
| ||||||||
404 |
|
Update End Point
API | Status Code | Response Body | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Endpoint: http://locator:8080/geode/v2/regions/Foo Method: PATCH Headers: user: user1 password: password1 Body:
| 200 |
| ||||||||||||||
400 |
| |||||||||||||||
401 |
| |||||||||||||||
403 |
| |||||||||||||||
404 |
| |||||||||||||||
500 |
|
Delete End Point
API | Status Code | Response Body | ||||||
---|---|---|---|---|---|---|---|---|
Endpoint: http://locator:8080/geode/v2/regions/Foo Method: DELETE Headers: user: user1 password: password1
| 204 | <Successful deletion> | ||||||
304 |
| |||||||
401 |
| |||||||
403 |
| |||||||
500 |
|
Note that the DELETE endpoint is idempotent – i.e. it should be a NOOP if the region does not exist.
Let's look at some code to see how users can use this service. The below example shows how to create a region using CMS.
Curl (any standard REST client)
Code Block | ||||
---|---|---|---|---|
| ||||
curl http://locator.host:8080/geode/v2/regions -XPOST -d ' { "regionConfig": { "name": "Foo" "type": "PARTITIONED" } }' |
On Client
...