0
# Akka Cluster
1

2
Akka Cluster provides a fault-tolerant decentralized peer-to-peer based cluster membership service with no single point of failure or single point of bottleneck. It uses gossip protocols and automatic failure detection to manage cluster membership, enabling applications to build fault-tolerant, decentralized systems with automatic membership management and cluster-aware routing.
3

4
## Package Information
5

6
- **Package Name**: akka-cluster
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "com.typesafe.akka" %% "akka-cluster" % "2.5.32"`
10
- **Maven Coordinates**: `com.typesafe.akka:akka-cluster_2.11:2.5.32`
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.cluster.MemberStatus
19
```
20

21
## Basic Usage
22

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

28
// Create actor system with cluster configuration
29
implicit val system = ActorSystem("ClusterSystem")
30
val cluster = Cluster(system)
31

32
// Subscribe to cluster events
33
val listener = system.actorOf(Props[ClusterListener])
34
cluster.subscribe(listener, 
35
  classOf[MemberEvent], 
36
  classOf[UnreachableMember], 
37
  classOf[ReachableMember])
38

39
// Join cluster
40
cluster.join(cluster.selfAddress)
41

42
// Check cluster state
43
val currentState = cluster.state
44
println(s"Members: ${currentState.members}")
45
println(s"Leader: ${currentState.leader}")
46

47
// Leave cluster gracefully
48
cluster.leave(cluster.selfAddress)
49
```
50

51
## Architecture
52

53
Akka Cluster is built around several key components:
54

55
- **Cluster Extension**: Main entry point (`Cluster` object and class) providing cluster membership operations
56
- **Gossip Protocol**: Decentralized information dissemination for cluster state synchronization
57
- **Failure Detection**: Automatic detection of unreachable nodes using configurable failure detectors
58
- **Event System**: Comprehensive event model for reacting to cluster state changes
59
- **Membership Management**: Automatic handling of node joining, leaving, and failure scenarios
60
- **Routing Integration**: Cluster-aware routing for distributing work across cluster nodes
61
- **Multi-Data Center Support**: Cross-data center clustering with separate failure detection
62

63
## Capabilities
64

65
### Cluster Membership Management
66

67
Core cluster operations for joining, leaving, and managing cluster membership. Essential for setting up distributed actor systems.
68

69
```scala { .api }
70
// Cluster extension access
71
object Cluster extends ExtensionId[Cluster]
72
def get(system: ActorSystem): Cluster
73

74
// Main cluster operations
75
class Cluster(system: ExtendedActorSystem) extends Extension {
76
  def join(address: Address): Unit
77
  def leave(address: Address): Unit
78
  def down(address: Address): Unit
79
  def state: CurrentClusterState
80
  def selfAddress: Address
81
  def selfRoles: Set[String]
82
}
83
```
84

85
[Cluster Management](./cluster-management.md)
86

87
### Event System and State Monitoring
88

89
Comprehensive event system for monitoring cluster state changes, member lifecycle events, and reachability updates.
90

91
```scala { .api }
92
// Event subscription
93
def subscribe(subscriber: ActorRef, to: Class[_]*): Unit
94
def unsubscribe(subscriber: ActorRef): Unit
95

96
// Core events
97
sealed trait ClusterDomainEvent
98
case class MemberUp(member: Member) extends MemberEvent
99
case class MemberLeft(member: Member) extends MemberEvent
100
case class UnreachableMember(member: Member) extends ReachabilityEvent
101
case class LeaderChanged(leader: Option[Address]) extends ClusterDomainEvent
102

103
// Current state
104
class CurrentClusterState(
105
  members: immutable.SortedSet[Member],
106
  unreachable: Set[Member],
107
  seenBy: Set[Address],
108
  leader: Option[Address]
109
)
110
```
111

112
[Events and State](./events-and-state.md)
113

114
### Member Information and Status
115

116
Member representation, status management, and member lifecycle including addressing and role-based organization.
117

118
```scala { .api }
119
// Member representation
120
class Member(
121
  uniqueAddress: UniqueAddress,
122
  status: MemberStatus,
123
  roles: Set[String]
124
) {
125
  def address: Address
126
  def hasRole(role: String): Boolean
127
  def isOlderThan(other: Member): Boolean
128
}
129

130
// Member status enumeration
131
sealed abstract class MemberStatus
132
case object Joining extends MemberStatus
133
case object Up extends MemberStatus  
134
case object Leaving extends MemberStatus
135
case object Down extends MemberStatus
136
```
137

138
[Members and Status](./members-and-status.md)
139

140
### Cluster-Aware Routing
141

142
Routing configuration for distributing work across cluster nodes with support for pools and groups, role-based routing.
143

144
```scala { .api }
145
// Cluster router configurations
146
case class ClusterRouterPool(
147
  local: Pool, 
148
  settings: ClusterRouterPoolSettings
149
) extends RouterConfig
150

151
case class ClusterRouterGroup(
152
  local: Group,
153
  settings: ClusterRouterGroupSettings  
154
) extends RouterConfig
155

156
// Router settings
157
case class ClusterRouterPoolSettings(
158
  totalInstances: Int,
159
  maxInstancesPerNode: Int,
160
  allowLocalRoutees: Boolean,
161
  useRoles: Set[String]
162
)
163
```
164

165
[Cluster Routing](./cluster-routing.md)
166

167
### Configuration and Settings
168

169
Cluster configuration management, settings, and JMX integration for monitoring and management.
170

171
```scala { .api }
172
// Configuration
173
class ClusterSettings(config: Config, systemName: String) {
174
  def SeedNodes: immutable.IndexedSeq[Address]
175
  def Roles: Set[String] 
176
  def SelfDataCenter: DataCenter
177
  def HeartbeatInterval: FiniteDuration
178
}
179

180
// JMX management interface
181
trait ClusterNodeMBean {
182
  def join(address: String): Unit
183
  def leave(address: String): Unit
184
  def down(address: String): Unit
185
  def getMemberStatus: String
186
  def getClusterStatus: String
187
}
188
```
189

190
[Configuration and Management](./configuration-and-management.md)
191

192
### Extensibility and SPI
193

194
Service Provider Interfaces for extending cluster behavior including custom downing strategies and join validation.
195

196
```scala { .api }
197
// Downing provider SPI
198
abstract class DowningProvider {
199
  def downRemovalMargin: FiniteDuration
200
  def downingActorProps: Option[Props]
201
}
202

203
// Configuration validation SPI  
204
abstract class JoinConfigCompatChecker {
205
  def requiredKeys: immutable.Seq[String]
206
  def check(toCheck: Config, actualConfig: Config): ConfigValidation
207
}
208
```
209

210
[Extensibility](./extensibility.md)
211

212
## Types
213

214
```scala { .api }
215
// Core addressing
216
case class UniqueAddress(address: Address, longUid: Long)
217
type DataCenter = String
218

219
// Subscription modes
220
sealed abstract class SubscriptionInitialStateMode
221
case object InitialStateAsSnapshot extends SubscriptionInitialStateMode
222
case object InitialStateAsEvents extends SubscriptionInitialStateMode
223

224
// Configuration validation result
225
sealed trait ConfigValidation
226
case object Valid extends ConfigValidation
227
case class Invalid(errorMessages: immutable.Seq[String]) extends ConfigValidation
228
```