0
# Akka Cluster
1

2
Akka Cluster provides fault-tolerant decentralized peer-to-peer cluster membership management with no single point of failure. It enables building resilient distributed systems using the Actor Model with features like gossip-based cluster membership, leader election, unreachable member detection, and cluster state management.
3

4
## Package Information
5

6
- **Package Name**: akka-cluster
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Full Coordinates**: com.typesafe.akka:akka-cluster_2.12:2.8.8
10
- **Installation**: Add to `build.sbt`: `libraryDependencies += "com.typesafe.akka" %% "akka-cluster" % "2.8.8"`
11

12
## Core Imports
13

14
```scala
15
import akka.cluster.Cluster
16
import akka.cluster.ClusterEvent._
17
import akka.cluster.Member
18
import akka.actor.{ActorSystem, Address}
19
```
20

21
## Basic Usage
22

23
```scala
24
import akka.actor.ActorSystem
25
import akka.cluster.{Cluster, ClusterEvent}
26
import akka.cluster.ClusterEvent._
27

28
implicit val system = ActorSystem("ClusterSystem")
29
val cluster = Cluster(system)
30

31
// Join cluster via seed nodes
32
val seedNodes = List(
33
  Address("akka", "ClusterSystem", "127.0.0.1", 2551),
34
  Address("akka", "ClusterSystem", "127.0.0.1", 2552)
35
)
36
cluster.joinSeedNodes(seedNodes)
37

38
// Subscribe to cluster events
39
cluster.subscribe(self, initialStateMode = InitialStateAsSnapshot, 
40
                 classOf[MemberEvent], classOf[UnreachableMember])
41

42
// React to events
43
def receive = {
44
  case MemberUp(member) =>
45
    println(s"Member is Up: ${member.address}")
46
  case UnreachableMember(member) =>
47
    println(s"Member detected as unreachable: ${member}")
48
  case MemberRemoved(member, previousStatus) =>
49
    println(s"Member is Removed: ${member.address} after $previousStatus")
50
  case _: MemberEvent => // ignore
51
}
52

53
// Graceful shutdown
54
cluster.leave(cluster.selfAddress)
55
```
56

57
## Architecture
58

59
Akka Cluster is built around several key components:
60

61
- **Cluster Extension**: Main entry point (`Cluster`) providing cluster operations and state access
62
- **Gossip Protocol**: Distributed consensus mechanism for sharing cluster state across nodes
63
- **Failure Detection**: Pluggable failure detectors for monitoring node health and reachability
64
- **Member Lifecycle**: State machine managing member transitions (Joining → Up → Leaving → Removed)
65
- **Event System**: Publisher-subscriber model for cluster state change notifications
66
- **Split Brain Resolution**: Configurable strategies for handling network partitions
67
- **Multi-Data Center**: Support for geographically distributed clusters with cross-DC communication
68

69
## Capabilities
70

71
### Cluster Management
72

73
Core cluster operations including joining, leaving, and managing cluster membership. Provides the main API for interacting with the cluster.
74

75
```scala { .api }
76
class Cluster(system: ExtendedActorSystem) extends Extension {
77
  // System and Configuration Access
78
  val system: ExtendedActorSystem
79
  val settings: ClusterSettings
80
  val failureDetector: FailureDetectorRegistry[Address]
81
  val crossDcFailureDetector: FailureDetectorRegistry[Address]
82
  lazy val downingProvider: DowningProvider
83
  
84
  // Basic Cluster Operations
85
  def join(address: Address): Unit
86
  def joinSeedNodes(seedNodes: immutable.Seq[Address]): Unit
87
  def joinSeedNodes(seedNodes: java.util.List[Address]): Unit  // Java API
88
  def leave(address: Address): Unit
89
  def down(address: Address): Unit
90
  def prepareForFullClusterShutdown(): Unit
91
  def isTerminated: Boolean
92
  
93
  // State Access  
94
  def state: CurrentClusterState
95
  def selfMember: Member
96
  def selfAddress: Address
97
  def selfUniqueAddress: UniqueAddress
98
  def selfDataCenter: DataCenter
99
  def selfRoles: Set[String]
100
  def getSelfRoles: java.util.Set[String]  // Java API
101
  def sendCurrentClusterState(receiver: ActorRef): Unit
102
  
103
  // Event Subscription
104
  def subscribe(subscriber: ActorRef, to: Class[_]*): Unit
105
  def subscribe(subscriber: ActorRef, initialStateMode: SubscriptionInitialStateMode, to: Class[_]*): Unit
106
  def unsubscribe(subscriber: ActorRef): Unit  
107
  def unsubscribe(subscriber: ActorRef, to: Class[_]): Unit
108
  
109
  // Lifecycle Callbacks
110
  def registerOnMemberUp[T](code: => T): Unit
111
  def registerOnMemberUp(callback: Runnable): Unit  // Java API
112
  def registerOnMemberRemoved[T](code: => T): Unit
113
  def registerOnMemberRemoved(callback: Runnable): Unit  // Java API
114
  
115
  // Utilities
116
  def setAppVersionLater(appVersion: Future[Version]): Unit
117
  def setAppVersionLater(appVersion: CompletionStage[Version]): Unit  // Java API
118
  def remotePathOf(actorRef: ActorRef): ActorPath
119
}
120

121
object Cluster extends ExtensionId[Cluster] {
122
  def apply(system: ActorSystem): Cluster
123
  def get(system: ActorSystem): Cluster
124
  def get(system: ClassicActorSystemProvider): Cluster
125
}
126
```
127

128
[Cluster Management](./cluster-management.md)
129

130
### Event System
131

132
Comprehensive event system for monitoring cluster state changes, member lifecycle events, and reachability status. Essential for building cluster-aware applications.
133

134
```scala { .api }
135
trait ClusterDomainEvent
136

137
case class CurrentClusterState(
138
  members: immutable.SortedSet[Member],
139
  unreachable: Set[Member],
140
  seenBy: Set[Address],
141
  leader: Option[Address],
142
  roleLeaderMap: Map[String, Option[Address]]
143
)
144

145
// Member Events
146
case class MemberUp(member: Member) extends MemberEvent
147
case class MemberJoined(member: Member) extends MemberEvent
148
case class MemberLeft(member: Member) extends MemberEvent
149
case class MemberRemoved(member: Member, previousStatus: MemberStatus) extends MemberEvent
150

151
// Reachability Events  
152
case class UnreachableMember(member: Member) extends ClusterDomainEvent
153
case class ReachableMember(member: Member) extends ClusterDomainEvent
154
```
155

156
[Event System](./event-system.md)
157

158
### Member Management
159

160
Representation and management of cluster members, including status tracking, role-based operations, and member comparison capabilities.
161

162
```scala { .api }
163
class Member(
164
  val uniqueAddress: UniqueAddress,
165
  val status: MemberStatus,
166
  val roles: Set[String],
167
  val appVersion: Version
168
) {
169
  def address: Address
170
  def dataCenter: DataCenter
171
  def hasRole(role: String): Boolean
172
  def isOlderThan(other: Member): Boolean
173
  def copy(status: MemberStatus): Member
174
}
175

176
// Member statuses
177
sealed abstract class MemberStatus
178
case object Joining extends MemberStatus
179
case object WeaklyUp extends MemberStatus
180
case object Up extends MemberStatus
181
case object Leaving extends MemberStatus
182
case object Exiting extends MemberStatus
183
case object Down extends MemberStatus
184
case object Removed extends MemberStatus
185
```
186

187
[Member Management](./member-management.md)
188

189
### Cluster Configuration
190

191
Comprehensive configuration system for cluster behavior, failure detection, gossip settings, and multi-data center operations.
192

193
```scala { .api }
194
class ClusterSettings(config: Config, systemName: String) {
195
  def SeedNodes: immutable.IndexedSeq[Address]
196
  def Roles: Set[String]
197
  def SelfDataCenter: DataCenter
198
  def MinNrOfMembers: Int
199
  def AppVersion: Version
200
  def GossipInterval: FiniteDuration
201
  def FailureDetectorImplementationClass: String
202
  def DowningProviderClassName: String
203
}
204
```
205

206
[Configuration](./configuration.md)
207

208
### Cluster Routing
209

210
Cluster-aware routing functionality for distributing work across cluster members, with support for both pool and group routing strategies.
211

212
```scala { .api }
213
case class ClusterRouterGroup(
214
  local: Group, 
215
  settings: ClusterRouterGroupSettings
216
) extends Group
217

218
case class ClusterRouterPool(
219
  local: Pool,
220
  settings: ClusterRouterPoolSettings  
221
) extends Pool
222

223
class ClusterRouterGroupSettings(
224
  totalInstances: Int,
225
  routeesPaths: immutable.Seq[String],
226
  allowLocalRoutees: Boolean,
227
  useRoles: Set[String]
228
)
229
```
230

231
[Cluster Routing](./cluster-routing.md)
232

233
### Split Brain Resolution
234

235
Advanced split brain resolution strategies for handling network partitions and maintaining cluster consistency during network failures.
236

237
```scala { .api }
238
abstract class DowningProvider {
239
  def downRemovalMargin: FiniteDuration
240
  def downingActorProps: Option[Props]
241
}
242

243
class SplitBrainResolverProvider(system: ActorSystem) extends DowningProvider
244
```
245

246
[Split Brain Resolution](./split-brain-resolution.md)
247

248
## Types
249

250
```scala { .api }
251
case class UniqueAddress(address: Address, uid: Long)
252

253
type DataCenter = String
254

255
sealed abstract class SubscriptionInitialStateMode
256
case object InitialStateAsSnapshot extends SubscriptionInitialStateMode  
257
case object InitialStateAsEvents extends SubscriptionInitialStateMode
258

259
trait MemberEvent extends ClusterDomainEvent {
260
  def member: Member
261
}
262

263
class ValidationError(val message: String, val cause: Option[Throwable] = None)
264
```