Cluster HTTP Management

Pekko Management Cluster HTTP is a Management extension that allows interaction with an pekko-cluster through an HTTP interface. This management extension exposes different operations to manage nodes in a cluster as well as health checks based on the cluster state.

The operations exposed are comparable to the Command Line Management tool or the JMX interface pekko-cluster provides.

Project Info¶

Dependencies¶

The Pekko Cluster HTTP Management is a separate jar file. Make sure to include it along with the core pekko-management library in your project:

sbt

Gradle

Maven

val PekkoManagementVersion = "1.1.0"
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-management" % PekkoManagementVersion,
  "org.apache.pekko" %% "pekko-management-cluster-http" % PekkoManagementVersion
)

def versions = [
  PekkoManagementVersion: "1.1.0",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "org.apache.pekko:pekko-management_${versions.ScalaBinary}:${versions.PekkoManagementVersion}"
  implementation "org.apache.pekko:pekko-management-cluster-http_${versions.ScalaBinary}:${versions.PekkoManagementVersion}"
}

<properties>
  <pekko.management.version>1.1.0</pekko.management.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-management_${scala.binary.version}</artifactId>
    <version>${pekko.management.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-management-cluster-http_${scala.binary.version}</artifactId>
    <version>${pekko.management.version}</version>
  </dependency>
</dependencies>

Pekko Cluster HTTP Management can be used with Apache Pekko 1.1.2 or later. You have to override the following Pekko dependencies by defining them explicitly in your build and define the Pekko version to the one that you are using. Latest patch version of Pekko is recommended and a later version than 1.1.2 can be used.

sbt

Gradle

Maven

val PekkoVersion = "1.1.2"
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-cluster-sharding" % PekkoVersion,
  "org.apache.pekko" %% "pekko-discovery" % PekkoVersion
)

def versions = [
  PekkoVersion: "1.1.2",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "org.apache.pekko:pekko-cluster-sharding_${versions.ScalaBinary}:${versions.PekkoVersion}"
  implementation "org.apache.pekko:pekko-discovery_${versions.ScalaBinary}:${versions.PekkoVersion}"
}

<properties>
  <pekko.version>1.1.2</pekko.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-cluster-sharding_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-discovery_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
</dependencies>

Running¶

To make sure the Pekko Cluster HTTP Management is running, register it with Pekko Management:

Scala

Java

copysourceval system = ActorSystem()
// Automatically loads Cluster Http Routes
PekkoManagement(system).start()

copysourceActorSystem system = ActorSystem.create();
PekkoManagement.get(system).start();

API Definition¶

The following table describes the usage of the API. All GET operations are exposed by default. POST, PUT and DELETE operations are only enabled if pekko.management.http.route-providers-read-only is set to false.

The expected format of address follows the Cluster URI convention. Example: pekko://Main@myhostname.com:3311

In the paths address is also allowed to be provided without the protocol prefix. Example: Main@myhostname.com:3311

Get /cluster/domain-events request query parameters¶

Example request:

GET /cluster/domain-events?type=MemberUp&type=LeaderChanged HTTP/1.1
Host: 192.168.1.23:7626

Example response:

HTTP/1.1 200 OK
Server: pekko-http/1.0.0
Date: Mon, 11 Jan 2021 21:02:37 GMT
Transfer-Encoding: chunked
Content-Type: text/event-stream

data:{"member":{"dataCenter":"default","roles":["dc-default"],"status":"Up","uniqueAddress":{"address":"pekko://default@127.0.0.1:2551","longUid":-2440990093160003086}},"type":"MemberUp"}
event:MemberUp

data:{"address":"pekko://default@127.0.0.1:2551","type":"LeaderChanged"}
event:LeaderChanged

Get /cluster/domain-events responses¶

Get /cluster/members responses¶

Example response:

 {
   "selfNode": "pekko.tcp://test@10.10.10.10:1111",
   "members": [
     {
       "node": "pekko.tcp://test@10.10.10.10:1111",
       "nodeUid": "1116964444",
       "status": "Up",
       "roles": []
     }
   ],
   "unreachable": [],
   "leader: "pekko.tcp://test@10.10.10.10:1111",
   "oldest: "pekko.tcp://test@10.10.10.10:1111"
 }

Where oldest is the oldest node in the current datacenter.

Post /cluster/members responses¶

Example response:

Joining pekko.tcp://test@10.10.10.10:111

Get /cluster/members/{address} responses¶

Example response:

{
  "node": "pekko.tcp://test@10.10.10.10:1111",
  "nodeUid": "-169203556",
  "status": "Up",
  "roles": []
}

Delete /cluster/members/{address} responses¶

Example response:

Leaving pekko.tcp://test@10.10.10.10:111

Put /cluster/members/{address} responses¶

Example response:

Downing pekko.tcp://test@10.10.10.10:111

Get /cluster/shard responses¶

Example response:

{ “entityTypeKeys”: [“ShoppingCart”] }

Get /cluster/shards/{name} responses¶

Example response:

 {
   "regions": [
     {
       "shardId": "1234",
       "numEntities": 30
     }
   ]
 }

Hosting the routes in an existing Pekko HTTP server¶

Starting PekkoMangement starts a Pekko HTTP server and hosts the Cluster HTTP Routes. The routes can also be added to an existing Pekko HTTP server. To access all the routes:

Scala

Java

copysourceval cluster = Cluster(system)
val allRoutes: Route = ClusterHttpManagementRoutes(cluster)

copysourceCluster cluster = Cluster.get(system);
Route allRoutes = ClusterHttpManagementRoutes.all(cluster);

Just the read only routes can be accessed:

Scala

Java

copysourceval readOnlyRoutes: Route = ClusterHttpManagementRoutes.readOnly(cluster)

copysourceRoute readOnlyRoutes = ClusterHttpManagementRoutes.readOnly(cluster);

Disable routes¶

The Cluster HTTP Routes are included by default when this module is used. It can be disabled with the following configuration, for example if the cluster membership health checks are to be included but not the other Cluster HTTP Routes.

pekko.management.http.routes {
  cluster-management = ""
}

Health checks¶

A cluster membership health check is included that is designed to be used as a readiness check.

By default the health check returns true when a node is either Up or WeaklyUp. Can be configured with pekko.management.cluster.health-checks.ready-states.

The cluster membership readiness check can be disabled with configuration:

pekko.management.health-checks.readiness-checks {
  cluster-membership = ""
}