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

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

val AkkaManagementVersion = "1.0.10"
libraryDependencies ++= Seq(
  "com.lightbend.akka.management" %% "akka-management" % AkkaManagementVersion,
  "com.lightbend.akka.management" %% "akka-management-cluster-http" % AkkaManagementVersion
)

Gradle

def versions = [
  AkkaManagementVersion: "1.0.10",
  ScalaBinary: "2.12"
]
dependencies {
  implementation "com.lightbend.akka.management:akka-management_${versions.ScalaBinary}:${versions.AkkaManagementVersion}"
  implementation "com.lightbend.akka.management:akka-management-cluster-http_${versions.ScalaBinary}:${versions.AkkaManagementVersion}"
}

Maven

<properties>
  <akka.management.version>1.0.10</akka.management.version>
  <scala.binary.version>2.12</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.lightbend.akka.management</groupId>
    <artifactId>akka-management_${scala.binary.version}</artifactId>
    <version>${akka.management.version}</version>
  </dependency>
  <dependency>
    <groupId>com.lightbend.akka.management</groupId>
    <artifactId>akka-management-cluster-http_${scala.binary.version}</artifactId>
    <version>${akka.management.version}</version>
  </dependency>
</dependencies>

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

sbt

val AkkaVersion = "2.6.9"
libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-cluster-sharding" % AkkaVersion,
  "com.typesafe.akka" % "akka-discovery" % AkkaVersion
)

Gradle

def versions = [
  AkkaVersion: "2.6.9",
  ScalaBinary: "2.12"
]
dependencies {
  implementation "com.typesafe.akka:akka-cluster-sharding_${versions.ScalaBinary}:${versions.AkkaVersion}"
  implementation "com.typesafe.akka:akka-discovery:${versions.AkkaVersion}"
}

Maven

<properties>
  <akka.version>2.6.9</akka.version>
  <scala.binary.version>2.12</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-cluster-sharding_${scala.binary.version}</artifactId>
    <version>${akka.version}</version>
  </dependency>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-discovery</artifactId>
    <version>${akka.version}</version>
  </dependency>
</dependencies>

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.

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/domain-events request query parameters

Example request:

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

Example response:

HTTP/1.1 200 OK
Server: akka-http/10.2.2
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":"akka://[email protected]:2551","longUid":-2440990093160003086}},"type":"MemberUp"}
event:MemberUp

data:{"address":"akka://[email protected]:2551","type":"LeaderChanged"}
event:LeaderChanged

Get /cluster/domain-events responses

Get /cluster/members responses

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

Example response:

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

Get /cluster/members/{address} responses

Example response:

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

Delete /cluster/members/{address} responses

Example response:

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

Put /cluster/members/{address} responses

Example response:

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

Get /cluster/shards/{name} responses

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 = ""
}