Cluster Management Service
Note: This feature is experimental and is subject to change in future releases of Apache Geode.
The cluster management service enables you to change the configuration of the cluster using a REST interface, and have these changes replicated to all the applicable servers and persisted within the cluster configuration service.
This REST interface differs from gfsh commands in:
The REST interface allows for a more programmable access.
Changes to all members of the cluster are applied in a consistent manner.
REST interface changes may be invoked from a server via a function or from any client application.
You can configure the cluster without having any servers running. Having a locator running is sufficient.
Not all gfsh commands and options are available with this REST interface.
Currently, Geode provides a Java client to interact with the REST interface. There is also a Golang client that interacts with the REST interface.
The cluster management service REST API adheres to standard REST semantics, so users can use POST, PATCH, DELETE, and GET to create, update, delete, and read, respectively.
See the versioned documentation at Cluster Management Service REST API for more details. This version of Geode uses the 1.14 Management REST API.
Cluster Management Configuration
Locators started by gfsh support the cluster management service REST API.
Three property settings must be in effect to enable the cluster management REST API. These are in effect, by default, for gfsh-initiated locators.
http-service-port
must be set to a non-zero value. If set to zero, no HTTP service is available for the locator. The default HTTP service port is 7070.enable-cluster-configuration
must be set to true. When set to false, all of the cluster management service REST API calls return errors.enable-management-rest-service
must be set to true. When set to false, the cluster management REST service does not start.
By default, cluster management REST service logging occurs at the debug level.
To increase logging to the info level,
set the system property -Dgeode.management.request.logging=true
when you start up locators.
Authentication and Authorization
Secure your cluster management service REST API
by implementing the SecurityManager
interface.
When the interface is implemented,
API requests require credentials.
Credentials can take the form of a username/password pair or a valid bearer token. By default, the cluster management service expects credentials in the form of a username and password, as in the example:
curl --user username:password http://example.com/management/regions
When the security-auth-token-enabled-components
property is set to
all
or management
,
the cluster management service expects credentials in the form of a valid bearer token.
For example:
curl -H "Authorization: Bearer Y6bXlwYXNzdzByZAo" http://example.com/management/regions
Java API
The Java client allows you to use the REST interface API in your Java application. To use the API:
Include
geode-management.jar
in your application’s classpath.Use the
ClusterManagementServiceBuilder
class to build aClusterManagementService
object, using the various methods available on the builder to set the connection configuration.
Example:
ClusterManagementService cmsClient = new ClusterManagementServiceBuilder()
.setHost("localhost")
.setPort("7070")
.build();
Region regionConfig = new Region();
ClusterManagementListResult<Region, RuntimeRegionInfo> list = cmsClient.list(region);
Golang Command Line Interface
A Golang client that interacts with this service is available at https://github.com/gemfire/tanzu-gemfire-management-cf-plugin.
After download, you can use it to interact with any running cluster. For example:
$ ./gemfire http://localhost:7070 list regions