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.5.3
JDK versions
Eclipse Temurin JDK 11
Eclipse Temurin JDK 17
Eclipse Temurin JDK 21
Scala versions2.13.14, 3.3.3
License
Readiness level
Supported, support is available from Lightbend
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.

The Akka dependencies are available from Akka’s library repository. To access them there, you need to configure the URL for this repository.

sbt
resolvers += "Akka library repository".at("https://repo.akka.io/maven")
Gradle
repositories {
    mavenCentral()
    maven {
        url "https://repo.akka.io/maven"
    }
}
Maven
<project>
  ...
  <repositories>
    <repository>
      <id>akka-repository</id>
      <name>Akka library repository</name>
      <url>https://repo.akka.io/maven</url>
    </repository>
  </repositories>
</project>

Additionally, add the dependencies as below.

sbt
val AkkaManagementVersion = "1.5.3"
libraryDependencies ++= Seq(
  "com.lightbend.akka.management" %% "akka-management" % AkkaManagementVersion,
  "com.lightbend.akka.management" %% "akka-management-cluster-http" % AkkaManagementVersion
)
Gradle
def versions = [
  AkkaManagementVersion: "1.5.3",
  ScalaBinary: "2.13"
]
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.5.3</akka.management.version>
  <scala.binary.version>2.13</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.9.3 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.9.3 can be used.

sbt
val AkkaVersion = "2.9.3"
libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-cluster-sharding" % AkkaVersion,
  "com.typesafe.akka" %% "akka-discovery" % AkkaVersion
)
Gradle
def versions = [
  AkkaVersion: "2.9.3",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.typesafe.akka:akka-cluster-sharding_${versions.ScalaBinary}:${versions.AkkaVersion}"
  implementation "com.typesafe.akka:akka-discovery_${versions.ScalaBinary}:${versions.AkkaVersion}"
}
Maven
<properties>
  <akka.version>2.9.3</akka.version>
  <scala.binary.version>2.13</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_${scala.binary.version}</artifactId>
    <version>${akka.version}</version>
  </dependency>
</dependencies>

Running

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

Scala
sourceval system = ActorSystem()
// Automatically loads Cluster Http Routes
AkkaManagement(system).start()
Java
sourceActorSystem 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/ PUT operation: Prepare-for-full-shutdown Executes a prepare for full shutdown operation in cluster.
/cluster/domain-events GET None Returns cluster domain events as they occur, in JSON-encoded SSE format.
/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/domain-events request query parameters

Query Parameter Description
type Optional. Specify event type(s) to include in response (see table). If not specified, all event types are included.
Event Type Description
ClusterDomainEvent cluster domain event (parent)
MemberEvent membership event (parent)
MemberJoined membership event - joined
MemberWeaklyUp membership event - transitioned to WeaklyUp
MemberUp membership event - transitioned to Up
MemberLeft membership event - left
MemberExited membership event - exited
MemberDowned membership event - downed
MemberRemoved membership event - removed
LeaderChanged cluster’s leader has changed
RoleLeaderChanged cluster’s role leader has changed
ClusterShuttingDown cluster is shutting down
ReachabilityEvent reachability event (parent)
UnreachableMember reachability event - member now unreachable
ReachableMember reachability event - member now reachable
DataCenterReachabilityEvent DC reachability event (parent)
UnreachableDataCenter DC reachability event - DC now unreachable
ReachableDataCenter DC reachability event - DC now reachable

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

Response code Description
200 Cluster events in Server-Sent-Event format (JSON)
500 Something went wrong.

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/shard responses

Response code Description
200 Shard entity type keys in JSON format

Example response:

{ “entityTypeKeys”: [“ShoppingCart”] }

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
sourceval cluster = Cluster(system)
val allRoutes: Route = ClusterHttpManagementRoutes(cluster)
Java
sourceCluster cluster = Cluster.get(system);
Route allRoutes = ClusterHttpManagementRoutes.all(cluster);

Just the read only routes can be accessed:

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