Akka Cluster in use (Part 4): Managing a Cluster

Table of contents

Reading Time: 3 minutes

Hello friends, I hope you all are safe in the COVID-19 pandemic and learning new tools and tech while staying at home.

In our last blog post on Akka Cluster, we saw an Akka Cluster in action and learnt about how the node(s) react to new nodes in the Cluster. Now when we know how to create & setup an Akka Cluster, let’s learn, how to manage an Akka Cluster?

Since running a cluster requires monitoring and maintenance which can be done only with proper management. But to manage an Akka Cluster what should we use? The answer is Akka HTTP Cluster Management which provides a set of HTTP endpoints via which we can manage our cluster.

Now what features does Akka HTTP Cluster Management provides?

Removing member(s) from the cluster.
Viewing the status and the health of the cluster and it’s members.
And, viewing the information about the cluster sharding distribution.

How to Configure Akka Management?

Before using Akka Management we need to configure it. It’s configuration includes a port and a host on which it will listen and react to the requests.

akka {
  management {
    http {
      hostname = "127.0.0.1"
      port = 8558
      route-providers-read-only = false
    }
  }
}

As a best practice, the port on which Akka Management will run should be separate from the the port used by Akka/Akka HTTP. As it helps in applying appropriate firewall rules for securing the cluster. Also, for security reasons, the route-providers-read-only configuration is set to true by default. So that no one can access the POST/PUT routes of the Akka Management. But for managing the cluster manually we need to set this configuration to false. For additional security, we can configure SSL on Akka Management.

How to Start Akka Management?

Once we have configured the Akka Management, we just have to start the HTTP server of the Akka Management.

import akka.management.scaladsl.AkkaManagement

AkkaManagement(actorSystem).start()

Generally, the HTTP server is started after the Actor System is created which is usually done during the application boot process.

How to Use Akka Management?

Now, when we have configured & started the Akka Management, we can manage the cluster via the following HTTP endpoints:

/cluster/members/ (GET) – This endpoint exposes the status of the cluster, like membership of the nodes, current state of the node, etc.
/cluster/members/ (POST) – With the help of this endpoint we can add new node(s) to the cluster having {address} as a field value passed with the request.
/cluster/members/{address} (GET) – This endpoint exposes the status of the node having {address} in the cluster.
/cluster/members/{address} (DELETE) – This endpoint executes the leave operation in the cluster for the node having {address}.
/cluster/members/{address} (PUT) – This endpoint can execute either the down operation or the leave operation in the cluster for the node having {address}. The operation executed depends on the operation field value present in the request.
/cluster/shards/{name} (GET) – This endpoint provides the shard info for the shard region with the provided {name}.

Use Akka Management

Finally, let’s use Akka Management to remove a Node from the cluster. For that first form the cluster by following the steps mentioned in the blog: Akka Cluster in use (Part 3): Setup a Local Akka Cluster. Once the cluster is formed, we can remove a node by using following Akka Management HTTP endpoint:

curl -w '\n' -X PUT -H 'Content-Type: multipart/form-data' -F operation=down http://localhost:8558/cluster/members/Credibility@127.0.0.1:2552

This will mark the Node running on port 2552 as DOWN. And the cluster’s state will look like following:

Whereas earlier, the cluster had 2 nodes in it.

Moreover, other Node(s) of the cluster will react to a Node’s DOWNing like following:

Where we can see that other Node(s) are marking the Node as DOWNed. Likewise, we can use other HTTP endpoints of Akka Managment to manage the cluster.

So, now we know how to manage an Akka Cluster via Akka Management. In our future posts we will get to know, how the Node(s) in an Akka Cluster communicate with each other. So stay tuned 🙂