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 have the change persisted in the cluster configuration for incoming servers, there is no public API for him to do so. He will have to 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 

User Goals

Create a more modular product to allow for easy extension and integration. The beneficiaries of this work are the developers working on different parts of the code such as Spring Data for Apache, Queries for Lucene index, storage for the JDBC connector, other Geode developers and anyone who wants to change the configuration of the cluster (create/destroy regions, indices or gateway receivers/senders etc), have these changes replicated on all the applicable servers and persisted in the configuration persistence service for new joining servers.

What We Have Now:

Our admin rest API "sort of" already serves this purpose, but it has these shortcomings:

1. It's not a public API
2. the APIincludesagfshcommandstring.
3. Each command does similar things yet not consistent with each other.

Below is a diagram of the current state of things:

From the current state of commands, It's not easy to extract a common interface for all the commands. And developers do not wanttousegfshcommandstringsas a "makeshift" API to call into the command. We are in need of a unified interface and a unified workflow for all the commands as well.

Proposal

A new Cluster Management Service (CMS) which has two responsibilities:

• Update runtime configuration of servers (if any running)
• Persist configuration (if enabled)

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, PUT, DELETE & GET to create, update, delete or read respectively. API returns a JSON body that contains a message describing the result along with returning standard HTTP status codes.

Create API

{
  "regionConfig": {
      "name"  : "Foo",
      "refId" : "REPLICATE"
  }
}

{
    "message": "Region created on server1, server2, server3"
}

{
    "message": "Region type is a required parameter"
}

{
    "message": "Region with name '/Foo' already exist"
}

{
    "message": "missing authorization parameters"
}

{
    "message": "user1 not authorized for DATA:MANAGE"
}

Update/Delete/Get API

{
  "regionConfig": {
      "name"  : "Foo"
  }
}

{
    "message": "Region '/Foo' destroyed on Server1, Server2, Server3"
}

{
    "message": "missing authorization parameters"
}

{
    "message": "user1 not authorized for DATA:MANAGE"
}

{
    "message": "Region with name '/Foo' 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)

curl http://locator.host:8080/configure?ifNotExists=true -XPOST -d '
{
  "regionConfig": {
      "name"  : "Foo",
      "refId" : "REPLICATE"
  }
}'

On Client