Using Akka’s ClusterClient

I’ve been spending some time implementing a feature which leverages Akka’s ClusterClient (api docs). A ClusterClient can be useful if:

• You are running a service which needs to talk to another service in a cluster, but you don’t that service to be in the cluster (cluster roles are another option for interconnecting services where separate hosts are necessary but I’m not sold on them just yet).
• You don’t want the overhead of running an http client/server interaction model between these services, but you’d like similar semantics. Spray is a great akka framework for api services but you may not want to write a Spray API or use an http client library.
• You want to use the same transparency of local-to-remote actors but don’t want to deal with remote actorref configurations to specific hosts.

The documentation was a little thin on some specifics so getting started wasn’t as smooth sailing as I’d like. Here are some gotchas:

• You only need akka.extensions = ["akka.contrib.pattern.ClusterReceptionistExtension"] on the Host (Server) Cluster. (If your client isn’t a cluster, you’ll get a runtime exception).
• “Receptionist” is the default name for the Host Cluster actor managing ClusterClient connections. Your ClusterClient connects first to the receptionist (via the set of initial contacts) then can start sending messages to actors in the Host Cluster. The name is configurable.
• The client actor system using the ClusterClient needs to have a Netty port open. You must use either actor.cluster.ClusterActorRefProvider or actor.remote.RemoteActorRefProvider. Otherwise the Host Cluster and ClusterClient can’t establish proper communication. You can use the ClusterActorRefProvider on the client even you’re not running a cluster.
• As a ClusterClient you wrap messages with a ClusterClient.send (or sendAll) message first. (I was sending vanilla messages and they weren’t going through, but this is in the docs).

ClusterClients are worth checking out if you want to create physically separate yet interconnected systems but don’t want to go through the whole load-balancer or http-layer setup. Just another tool in the Akka toolbelt!