CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-typesafe-akka--akka-cluster-tools-2-13

Akka Cluster Tools provides utilities for building clustered applications including cluster singleton, distributed publish-subscribe, and cluster client functionality

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Akka Cluster Tools

Akka Cluster Tools provides essential utilities for building distributed applications with Akka Cluster. It includes cluster singleton management for exactly-one-instance patterns, distributed publish-subscribe for decoupled messaging, and cluster client functionality for external system integration.

Package Information

  • Package Name: com.typesafe.akka:akka-cluster-tools_2.13
  • Package Type: Maven
  • Language: Scala
  • Installation: libraryDependencies += "com.typesafe.akka" %% "akka-cluster-tools" % "2.8.8"

Core Imports

import akka.cluster.singleton.{ClusterSingletonManager, ClusterSingletonProxy}
import akka.cluster.pubsub.{DistributedPubSub, DistributedPubSubMediator}
import akka.cluster.client.{ClusterClient, ClusterClientReceptionist}

Basic Usage

import akka.actor.{ActorSystem, Props}
import akka.cluster.singleton.{ClusterSingletonManager, ClusterSingletonManagerSettings}
import akka.cluster.pubsub.DistributedPubSub
import akka.cluster.pubsub.DistributedPubSubMediator.{Publish, Subscribe}

implicit val system: ActorSystem = ActorSystem("cluster-system")

// Create a cluster singleton
val singletonManager = system.actorOf(
  ClusterSingletonManager.props(
    singletonProps = Props[MyWorkerActor](),
    terminationMessage = "stop",
    settings = ClusterSingletonManagerSettings(system)
  ),
  name = "workerSingleton"
)

// Use distributed pub-sub
val mediator = DistributedPubSub(system).mediator
mediator ! Subscribe("news", self)
mediator ! Publish("news", "Breaking: Akka cluster is operational!")

Architecture

Akka Cluster Tools is built around three core patterns for distributed systems:

  • Cluster Singleton: Ensures exactly one instance of a critical actor runs across the entire cluster, with automatic failover
  • Distributed Pub-Sub: Enables location-transparent messaging between actors across cluster nodes without direct references
  • Cluster Client: Provides a gateway for external systems to communicate with cluster actors (deprecated since 2.6.0)

Each pattern addresses different distributed system challenges:

  • Singleton: Leadership election, resource coordination, central state management
  • Pub-Sub: Event-driven architecture, loose coupling, dynamic topology handling
  • Client: External integration, protocol bridging, cluster boundary management

Capabilities

Cluster Singleton Management

Manages a singleton actor instance across cluster nodes with automatic failover and hand-over coordination.

class ClusterSingletonManager(
  singletonProps: Props,
  terminationMessage: Any,
  settings: ClusterSingletonManagerSettings
)

object ClusterSingletonManager {
  def props(
    singletonProps: Props,
    terminationMessage: Any,
    settings: ClusterSingletonManagerSettings
  ): Props
}

class ClusterSingletonProxy(
  singletonManagerPath: String,
  settings: ClusterSingletonProxySettings
)

object ClusterSingletonProxy {
  def props(
    singletonManagerPath: String,
    settings: ClusterSingletonProxySettings
  ): Props
}

Cluster Singleton

Distributed Publish-Subscribe

Location-transparent publish-subscribe messaging system that works across cluster nodes.

class DistributedPubSubMediator(settings: DistributedPubSubSettings)

object DistributedPubSubMediator {
  def props(settings: DistributedPubSubSettings): Props
  
  case class Subscribe(topic: String, group: Option[String], ref: ActorRef)
  case class Publish(topic: String, msg: Any, sendOneMessageToEachGroup: Boolean)
  case class Send(path: String, msg: Any, localAffinity: Boolean)
  case class SendToAll(path: String, msg: Any, allButSelf: Boolean)
}

object DistributedPubSub extends ExtensionId[DistributedPubSub] {
  def get(system: ActorSystem): DistributedPubSub
}

class DistributedPubSub(system: ExtendedActorSystem) extends Extension {
  def mediator: ActorRef
}

Distributed Publish-Subscribe

Cluster Client (Deprecated)

Client-side gateway for external systems to communicate with cluster actors. Deprecated since Akka 2.6.0 in favor of Akka gRPC.

@deprecated("Use Akka gRPC instead", since = "2.6.0")
class ClusterClient(settings: ClusterClientSettings)

@deprecated("Use Akka gRPC instead", since = "2.6.0") 
object ClusterClient {
  def props(settings: ClusterClientSettings): Props
  
  case class Send(path: String, msg: Any, localAffinity: Boolean)
  case class SendToAll(path: String, msg: Any)
  case class Publish(topic: String, msg: Any)
}

Cluster Client

Common Types

// Configuration classes
final class ClusterSingletonManagerSettings(
  singletonName: String,
  role: Option[String],
  removalMargin: FiniteDuration,
  handOverRetryInterval: FiniteDuration,
  leaseSettings: Option[LeaseUsageSettings]
) {
  def withSingletonName(name: String): ClusterSingletonManagerSettings
  def withRole(role: String): ClusterSingletonManagerSettings
  def withRole(role: Option[String]): ClusterSingletonManagerSettings
  def withRemovalMargin(removalMargin: FiniteDuration): ClusterSingletonManagerSettings
  def withHandOverRetryInterval(retryInterval: FiniteDuration): ClusterSingletonManagerSettings
  def withLeaseSettings(leaseSettings: LeaseUsageSettings): ClusterSingletonManagerSettings
}

object ClusterSingletonManagerSettings {
  def apply(system: ActorSystem): ClusterSingletonManagerSettings
  def apply(config: Config): ClusterSingletonManagerSettings
  def create(system: ActorSystem): ClusterSingletonManagerSettings
  def create(config: Config): ClusterSingletonManagerSettings
}

final class ClusterSingletonProxySettings(
  singletonName: String,
  role: Option[String],
  dataCenter: Option[DataCenter],
  singletonIdentificationInterval: FiniteDuration,
  bufferSize: Int
) {
  def withSingletonName(name: String): ClusterSingletonProxySettings
  def withRole(role: String): ClusterSingletonProxySettings
  def withRole(role: Option[String]): ClusterSingletonProxySettings
  def withDataCenter(dataCenter: DataCenter): ClusterSingletonProxySettings
  def withDataCenter(dataCenter: Option[DataCenter]): ClusterSingletonProxySettings
  def withSingletonIdentificationInterval(interval: FiniteDuration): ClusterSingletonProxySettings
  def withBufferSize(bufferSize: Int): ClusterSingletonProxySettings
}

object ClusterSingletonProxySettings {
  def apply(system: ActorSystem): ClusterSingletonProxySettings
  def apply(config: Config): ClusterSingletonProxySettings
  def create(system: ActorSystem): ClusterSingletonProxySettings
  def create(config: Config): ClusterSingletonProxySettings
}

final class DistributedPubSubSettings(
  role: Option[String],
  routingLogic: RoutingLogic,
  gossipInterval: FiniteDuration,
  removedTimeToLive: FiniteDuration,
  maxDeltaElements: Int,
  sendToDeadLettersWhenNoSubscribers: Boolean
)

// Import types from Akka core
import akka.actor.{ActorRef, ActorSystem, Props}
import akka.cluster.ClusterSettings.DataCenter
import akka.coordination.lease.LeaseUsageSettings
import akka.routing.RoutingLogic
import com.typesafe.config.Config
import scala.concurrent.duration.FiniteDuration
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.typesafe.akka/akka-cluster-tools_2.13@2.8.x
Publish Source
CLI
Badge
tessl/maven-com-typesafe-akka--akka-cluster-tools-2-13 badge