0
# Akka Cluster Tools
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: com.typesafe.akka:akka-cluster-tools_2.13  
7
- **Package Type**: Maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "com.typesafe.akka" %% "akka-cluster-tools" % "2.8.8"`
10

11
## Core Imports
12

13
```scala
14
import akka.cluster.singleton.{ClusterSingletonManager, ClusterSingletonProxy}
15
import akka.cluster.pubsub.{DistributedPubSub, DistributedPubSubMediator}
16
import akka.cluster.client.{ClusterClient, ClusterClientReceptionist}
17
```
18

19
## Basic Usage
20

21
```scala
22
import akka.actor.{ActorSystem, Props}
23
import akka.cluster.singleton.{ClusterSingletonManager, ClusterSingletonManagerSettings}
24
import akka.cluster.pubsub.DistributedPubSub
25
import akka.cluster.pubsub.DistributedPubSubMediator.{Publish, Subscribe}
26

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

29
// Create a cluster singleton
30
val singletonManager = system.actorOf(
31
  ClusterSingletonManager.props(
32
    singletonProps = Props[MyWorkerActor](),
33
    terminationMessage = "stop",
34
    settings = ClusterSingletonManagerSettings(system)
35
  ),
36
  name = "workerSingleton"
37
)
38

39
// Use distributed pub-sub
40
val mediator = DistributedPubSub(system).mediator
41
mediator ! Subscribe("news", self)
42
mediator ! Publish("news", "Breaking: Akka cluster is operational!")
43
```
44

45
## Architecture
46

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

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

53
Each pattern addresses different distributed system challenges:
54
- Singleton: Leadership election, resource coordination, central state management
55
- Pub-Sub: Event-driven architecture, loose coupling, dynamic topology handling  
56
- Client: External integration, protocol bridging, cluster boundary management
57

58
## Capabilities
59

60
### Cluster Singleton Management
61

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

64
```scala { .api }
65
class ClusterSingletonManager(
66
  singletonProps: Props,
67
  terminationMessage: Any,
68
  settings: ClusterSingletonManagerSettings
69
)
70

71
object ClusterSingletonManager {
72
  def props(
73
    singletonProps: Props,
74
    terminationMessage: Any,
75
    settings: ClusterSingletonManagerSettings
76
  ): Props
77
}
78

79
class ClusterSingletonProxy(
80
  singletonManagerPath: String,
81
  settings: ClusterSingletonProxySettings
82
)
83

84
object ClusterSingletonProxy {
85
  def props(
86
    singletonManagerPath: String,
87
    settings: ClusterSingletonProxySettings
88
  ): Props
89
}
90
```
91

92
[Cluster Singleton](./cluster-singleton.md)
93

94
### Distributed Publish-Subscribe
95

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

98
```scala { .api }
99
class DistributedPubSubMediator(settings: DistributedPubSubSettings)
100

101
object DistributedPubSubMediator {
102
  def props(settings: DistributedPubSubSettings): Props
103
  
104
  case class Subscribe(topic: String, group: Option[String], ref: ActorRef)
105
  case class Publish(topic: String, msg: Any, sendOneMessageToEachGroup: Boolean)
106
  case class Send(path: String, msg: Any, localAffinity: Boolean)
107
  case class SendToAll(path: String, msg: Any, allButSelf: Boolean)
108
}
109

110
object DistributedPubSub extends ExtensionId[DistributedPubSub] {
111
  def get(system: ActorSystem): DistributedPubSub
112
}
113

114
class DistributedPubSub(system: ExtendedActorSystem) extends Extension {
115
  def mediator: ActorRef
116
}
117
```
118

119
[Distributed Publish-Subscribe](./distributed-pubsub.md)
120

121
### Cluster Client (Deprecated)
122

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

125
```scala { .api }
126
@deprecated("Use Akka gRPC instead", since = "2.6.0")
127
class ClusterClient(settings: ClusterClientSettings)
128

129
@deprecated("Use Akka gRPC instead", since = "2.6.0") 
130
object ClusterClient {
131
  def props(settings: ClusterClientSettings): Props
132
  
133
  case class Send(path: String, msg: Any, localAffinity: Boolean)
134
  case class SendToAll(path: String, msg: Any)
135
  case class Publish(topic: String, msg: Any)
136
}
137
```
138

139
[Cluster Client](./cluster-client.md)
140

141
## Common Types
142

143
```scala { .api }
144
// Configuration classes
145
final class ClusterSingletonManagerSettings(
146
  singletonName: String,
147
  role: Option[String],
148
  removalMargin: FiniteDuration,
149
  handOverRetryInterval: FiniteDuration,
150
  leaseSettings: Option[LeaseUsageSettings]
151
) {
152
  def withSingletonName(name: String): ClusterSingletonManagerSettings
153
  def withRole(role: String): ClusterSingletonManagerSettings
154
  def withRole(role: Option[String]): ClusterSingletonManagerSettings
155
  def withRemovalMargin(removalMargin: FiniteDuration): ClusterSingletonManagerSettings
156
  def withHandOverRetryInterval(retryInterval: FiniteDuration): ClusterSingletonManagerSettings
157
  def withLeaseSettings(leaseSettings: LeaseUsageSettings): ClusterSingletonManagerSettings
158
}
159

160
object ClusterSingletonManagerSettings {
161
  def apply(system: ActorSystem): ClusterSingletonManagerSettings
162
  def apply(config: Config): ClusterSingletonManagerSettings
163
  def create(system: ActorSystem): ClusterSingletonManagerSettings
164
  def create(config: Config): ClusterSingletonManagerSettings
165
}
166

167
final class ClusterSingletonProxySettings(
168
  singletonName: String,
169
  role: Option[String],
170
  dataCenter: Option[DataCenter],
171
  singletonIdentificationInterval: FiniteDuration,
172
  bufferSize: Int
173
) {
174
  def withSingletonName(name: String): ClusterSingletonProxySettings
175
  def withRole(role: String): ClusterSingletonProxySettings
176
  def withRole(role: Option[String]): ClusterSingletonProxySettings
177
  def withDataCenter(dataCenter: DataCenter): ClusterSingletonProxySettings
178
  def withDataCenter(dataCenter: Option[DataCenter]): ClusterSingletonProxySettings
179
  def withSingletonIdentificationInterval(interval: FiniteDuration): ClusterSingletonProxySettings
180
  def withBufferSize(bufferSize: Int): ClusterSingletonProxySettings
181
}
182

183
object ClusterSingletonProxySettings {
184
  def apply(system: ActorSystem): ClusterSingletonProxySettings
185
  def apply(config: Config): ClusterSingletonProxySettings
186
  def create(system: ActorSystem): ClusterSingletonProxySettings
187
  def create(config: Config): ClusterSingletonProxySettings
188
}
189

190
final class DistributedPubSubSettings(
191
  role: Option[String],
192
  routingLogic: RoutingLogic,
193
  gossipInterval: FiniteDuration,
194
  removedTimeToLive: FiniteDuration,
195
  maxDeltaElements: Int,
196
  sendToDeadLettersWhenNoSubscribers: Boolean
197
)
198

199
// Import types from Akka core
200
import akka.actor.{ActorRef, ActorSystem, Props}
201
import akka.cluster.ClusterSettings.DataCenter
202
import akka.coordination.lease.LeaseUsageSettings
203
import akka.routing.RoutingLogic
204
import com.typesafe.config.Config
205
import scala.concurrent.duration.FiniteDuration
206
```