Cluster HTTP Management

Akka Management Cluster HTTP is a Management extension that allows interaction with an akka-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 akka-cluster provides.

Project Info

Project Info: Akka Management Cluster HTTP
Artifact
com.lightbend.akka.management
akka-management-cluster-http
1.0.1
JDK versions
Adopt OpenJDK 8 with Hotspot
Adopt OpenJDK 11 with Hotspot
Scala versions2.11.12, 2.12.8, 2.13.0-M5
License
Readiness level
Since 1.0.0, 2019-03-15
Home pagehttps://akka.io/
API documentation
Forums
Release notesGitHub releases
IssuesGitHub issues
Sourceshttps://github.com/akka/akka-management

Dependencies

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

sbt
libraryDependencies ++= Seq(
  "com.lightbend.akka.management" %% "akka-management" % "1.0.1",
  "com.lightbend.akka.management" %% "akka-management-cluster-http" % "1.0.1"
)
Gradle
dependencies {
  compile group: 'com.lightbend.akka.management', name: 'akka-management_2.12', version: '1.0.1',
  compile group: 'com.lightbend.akka.management', name: 'akka-management-cluster-http_2.12', version: '1.0.1'
}
Maven
<dependency>
  <groupId>com.lightbend.akka.management</groupId>
  <artifactId>akka-management_2.12</artifactId>
  <version>1.0.1</version>
</dependency>
<dependency>
  <groupId>com.lightbend.akka.management</groupId>
  <artifactId>akka-management-cluster-http_2.12</artifactId>
  <version>1.0.1</version>
</dependency>

Running

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

Scala
val system = ActorSystem()
// Automatically loads Cluster Http Routes
AkkaManagement(system).start()
Java
ActorSystem system = ActorSystem.create();
AkkaManagement.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 akka.management.http.route-providers-read-only is set to false.

Path HTTP method Required form fields Description
/cluster/members/ GET None Returns the status of the Cluster in JSON format.
/cluster/members/ POST address: {address} Executes join operation in cluster for the provided {address}.
/cluster/members/{address} GET None Returns the status of {address} in the Cluster in JSON format.
/cluster/members/{address} DELETE None Executes leave operation in cluster for provided {address}.
/cluster/members/{address} PUT operation: Down Executes down operation in cluster for provided {address}.
/cluster/members/{address} PUT operation: Leave Executes leave operation in cluster for provided {address}.
/cluster/shards/{name} GET None Returns shard info for the shard region with the provided {name}

The expected format of address follows the Cluster URI convention. Example: akka://[email protected]:3311

In the paths address is also allowed to be provided without the protocol prefix. Example: [email protected]:3311

Get /cluster/members responses

Response code Description
200 Status of cluster in JSON format
500 Something went wrong. Cluster might be shutdown.

Example response:

 {
   "selfNode": "akka.tcp://[email protected]:1111",
   "members": [
     {
       "node": "akka.tcp://[email protected]:1111",
       "nodeUid": "1116964444",
       "status": "Up",
       "roles": []
     }
   ],
   "unreachable": [],
   "leader: "akka.tcp://[email protected]:1111",
   "oldest: "akka.tcp://[email protected]:1111"
 }

Where oldest is the oldest node in the current datacenter.

Post /cluster/members responses

Response code Description
200 Executing join operation.
500 Something went wrong. Cluster might be shutdown.

Example response:

Joining akka.tcp://[email protected]:111

Get /cluster/members/{address} responses

Response code Description
200 Status of cluster in JSON format
404 No member was found in the cluster for the given {address}.
500 Something went wrong. Cluster might be shutdown.

Example response:

{
  "node": "akka.tcp://[email protected]:1111",
  "nodeUid": "-169203556",
  "status": "Up",
  "roles": []
}

Delete /cluster/members/{address} responses

Response code Description
200 Executing leave operation.
404 No member was found in the cluster for the given {address}.
500 Something went wrong. Cluster might be shutdown.

Example response:

Leaving akka.tcp://[email protected]:111

Put /cluster/members/{address} responses

Response code Operation Description
200 Down Executing down operation.
200 Leave Executing leave operation.
400 Operation supplied in operation form field is not supported.
404 No member was found in the cluster for the given {address}
500 Something went wrong. Cluster might be shutdown.

Example response:

Downing akka.tcp://[email protected]:111

Get /cluster/shards/{name} responses

Response code Description
200 Shard region information in JSON format
404 No shard region was found on the node for the given {name}

Example response:

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

Hosting the routes in an existing Akka HTTP server

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

Scala
val cluster = Cluster(system)
val allRoutes: Route = ClusterHttpManagementRoutes(cluster)
Java
Cluster cluster = Cluster.get(system);
Route allRoutes = ClusterHttpManagementRoutes.all(cluster);

Just the read only routes can be accessed:

Scala
val readOnlyRoutes: Route = ClusterHttpManagementRoutes.readOnly(cluster)
Java
Route 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.

akka.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 akka.management.cluster.health-checks.ready-states.

The cluster membership readiness check can be disabled with configuration:

akka.management.health-checks.readiness-checks {
  cluster-membership = ""
}
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.