0
# Configuration
1

2
Akka Cluster configuration is managed through the `ClusterSettings` class and Typesafe Config. This covers all aspects of cluster behavior including membership, failure detection, gossip protocols, and multi-data center operations.
3

4
## ClusterSettings API
5

6
### Settings Class
7

8
```scala { .api }
9
class ClusterSettings(config: Config, systemName: String) {
10
  // Basic cluster settings
11
  def SeedNodes: immutable.IndexedSeq[Address]
12
  def Roles: Set[String]
13
  def SelfDataCenter: DataCenter
14
  def MinNrOfMembers: Int
15
  def MinNrOfMembersOfRole: Map[String, Int]
16
  def AppVersion: Version
17
  
18
  // Logging and monitoring
19
  def LogInfo: Boolean
20
  def LogInfoVerbose: Boolean
21
  def JmxEnabled: Boolean
22
  def JmxMultiMbeansInSameEnabled: Boolean
23
  def PublishStatsInterval: Duration
24
  
25
  // Failure detection settings
26
  def FailureDetectorImplementationClass: String
27
  def FailureDetectorConfig: Config
28
  def HeartbeatInterval: Duration
29
  def HeartbeatExpectedResponseAfter: Duration
30
  def MonitoredByNrOfMembers: Int
31
  
32
  // Downing provider
33
  def DowningProviderClassName: String
34
  
35
  // Timing and lifecycle settings
36
  def SeedNodeTimeout: Duration
37
  def RetryUnsuccessfulJoinAfter: Duration
38
  def WeaklyUpAfter: Duration
39
  def AllowWeaklyUpMembers: Boolean
40
  def DownRemovalMargin: Duration
41
  def QuarantineRemovedNodeAfter: Duration
42
  def PruneGossipTombstonesAfter: Duration
43
  
44
  // Gossip protocol settings
45
  def GossipInterval: FiniteDuration
46
  def GossipTimeToLive: FiniteDuration
47
  def GossipDifferentViewProbability: Double
48
  def ReduceGossipDifferentViewProbability: Int
49
  def LeaderActionsInterval: FiniteDuration
50
  def UnreachableNodesReaperInterval: FiniteDuration
51
  
52
  // Scheduler settings
53
  def PeriodicTasksInitialDelay: Duration
54
  def SchedulerTickDuration: Duration
55
  def SchedulerTicksPerWheel: Int
56
  
57
  // Configuration management
58
  def UseDispatcher: String
59
  def RunCoordinatedShutdownWhenDown: Boolean
60
  def ByPassConfigCompatCheck: Boolean
61
  def ConfigCompatCheckers: List[String]
62
  def SensitiveConfigPaths: List[String]
63
  
64
  // Debug settings
65
  def Debug: ClusterSettings.Debug
66
}
67

68
object ClusterSettings {
69
  type DataCenter = String
70
  
71
  val DefaultDataCenter: DataCenter = "default"
72
  
73
  object Debug {
74
    def VerboseHeartbeatLogging: Boolean
75
    def VerboseGossipLogging: Boolean
76
  }
77
}
78
```
79

80
### Settings Access
81

82
```scala
83
val cluster = Cluster(system)
84
val settings = cluster.settings
85

86
println(s"Seed nodes: ${settings.SeedNodes}")
87
println(s"Roles: ${settings.Roles}")
88
println(s"Min members: ${settings.MinNrOfMembers}")
89
println(s"Data center: ${settings.SelfDataCenter}")
90
println(s"Gossip interval: ${settings.GossipInterval}")
91
```
92

93
## Basic Cluster Configuration
94

95
### Essential Settings
96

97
```hocon
98
akka {
99
  actor {
100
    provider = cluster
101
  }
102
  
103
  cluster {
104
    # Seed nodes for cluster discovery
105
    seed-nodes = [
106
      "akka://ClusterSystem@127.0.0.1:2551",
107
      "akka://ClusterSystem@127.0.0.1:2552"
108
    ]
109
    
110
    # Minimum number of members before leader actions
111
    min-nr-of-members = 3
112
    
113
    # Node roles for role-based operations
114
    roles = ["backend", "compute"]
115
    
116
    # Application version for compatibility checking
117
    app-version = "1.0.0"
118
  }
119
  
120
  remote.artery {
121
    canonical.hostname = "127.0.0.1"
122
    canonical.port = 2551
123
  }
124
}
125
```
126

127
### Role-Based Minimum Members
128

129
```hocon
130
akka.cluster {
131
  role {
132
    # Minimum 2 backend nodes before any backend node becomes Up
133
    backend.min-nr-of-members = 2
134
    
135
    # Minimum 1 frontend node
136
    frontend.min-nr-of-members = 1
137
  }
138
}
139
```
140

141
## Failure Detection Configuration
142

143
### Default Failure Detector
144

145
```hocon
146
akka.cluster {
147
  # Failure detector implementation
148
  failure-detector {
149
    implementation-class = "akka.remote.PhiAccrualFailureDetector"
150
    
151
    # How often keep-alive heartbeat messages should be sent to each connection
152
    heartbeat-interval = 1s
153
    
154
    # Defines the failure detector threshold
155
    threshold = 8.0
156
    
157
    # Number of potentially lost/delayed heartbeats that will be
158
    # accepted before considering it to be an anomaly
159
    max-sample-size = 1000
160
    
161
    # Minimum standard deviation to use for the normal distribution in AccrualFailureDetector
162
    min-std-deviation = 100ms
163
    
164
    # Number of member nodes that each member will send heartbeat messages to
165
    monitored-by-nr-of-members = 5
166
  }
167
}
168
```
169

170
### Custom Failure Detector
171

172
```scala
173
class CustomFailureDetector extends FailureDetector {
174
  def isAvailable: Boolean = // custom logic
175
  def isMonitoring: Boolean = // custom logic  
176
  def heartbeat(): Unit = // custom logic
177
}
178
```
179

180
```hocon
181
akka.cluster.failure-detector {
182
  implementation-class = "com.example.CustomFailureDetector"
183
  # Custom failure detector specific configuration
184
  custom-setting = "value"
185
}
186
```
187

188
## Gossip Protocol Configuration
189

190
### Gossip Settings
191

192
```hocon
193
akka.cluster {
194
  # How often cluster nodes gossip membership information
195
  gossip-interval = 1s
196
  
197
  # Time to live for gossip messages
198
  gossip-time-to-live = 2s
199
  
200
  # How often leader performs maintenance tasks
201
  leader-actions-interval = 1s
202
  
203
  # How often unreachable nodes reaper runs
204
  unreachable-nodes-reaper-interval = 1s
205
  
206
  # Gossip to random node with newer gossip
207
  gossip-different-view-probability = 0.8
208
  
209
  # Reduced gossip frequency during convergence
210
  reduce-gossip-different-view-probability = 400
211
}
212
```
213

214
### Gossip Protocol Tuning
215

216
```hocon
217
akka.cluster {
218
  # Disable particular gossiping to speed up large cluster convergence
219
  gossip-different-view-probability = 0.4
220
  
221
  # For large clusters (>100 nodes)
222
  gossip-interval = 2s
223
  leader-actions-interval = 2s
224
  
225
  # For high-latency networks
226
  gossip-time-to-live = 5s
227
}
228
```
229

230
## Multi-Data Center Configuration
231

232
### Multi-DC Settings
233

234
```scala { .api }
235
object MultiDataCenterSettings {
236
  def CrossDcConnections: Int
237
  def CrossDcGossipProbability: Double
238
  def CrossDcFailureDetectorSettings: FailureDetectorSettings
239
}
240
```
241

242
### Configuration Example
243

244
```hocon
245
akka.cluster {
246
  multi-data-center {
247
    # Data center this node belongs to
248
    self-data-center = "dc-east"
249
    
250
    # Number of connections to other data centers
251
    cross-data-center-connections = 5
252
    
253
    # Probability of gossiping to other data centers
254
    cross-data-center-gossip-probability = 0.2
255
    
256
    # Failure detector for cross data center connections
257
    failure-detector {
258
      heartbeat-interval = 3s
259
      acceptable-heartbeat-pause = 10s
260
      threshold = 12.0
261
    }
262
  }
263
}
264
```
265

266
### Data Center Roles
267

268
```hocon
269
akka.cluster {
270
  # Automatically assigned based on self-data-center
271
  roles = ["dc-east", "backend"]
272
  
273
  multi-data-center {
274
    self-data-center = "east"
275
  }
276
}
277
```
278

279
## Downing Provider Configuration
280

281
### Default (No Downing)
282

283
```hocon
284
akka.cluster {
285
  downing-provider-class = "akka.cluster.NoDowning"
286
}
287
```
288

289
### Split Brain Resolver
290

291
```hocon
292
akka.cluster {
293
  downing-provider-class = "akka.cluster.sbr.SplitBrainResolverProvider"
294
  
295
  split-brain-resolver {
296
    # Strategy to use: keep-majority, lease-majority, static-quorum, keep-oldest, down-all
297
    active-strategy = "keep-majority"
298
    
299
    # Time margin after downing after which members will be removed
300
    stable-after = 20s
301
    
302
    # Down all members if cluster size is less than this
303
    down-all-when-unstable = "on"
304
  }
305
}
306
```
307

308
### Custom Downing Provider
309

310
```scala
311
class CustomDowningProvider(system: ActorSystem) extends DowningProvider {
312
  override def downRemovalMargin: FiniteDuration = 10.seconds
313
  override def downingActorProps: Option[Props] = 
314
    Some(Props(classOf[CustomDowningActor]))
315
}
316
```
317

318
```hocon
319
akka.cluster.downing-provider-class = "com.example.CustomDowningProvider"
320
```
321

322
## Logging and Monitoring
323

324
### Logging Configuration
325

326
```hocon
327
akka.cluster {
328
  # Enable cluster info logging
329
  log-info = on
330
  
331
  # Enable verbose cluster info logging  
332
  log-info-verbose = off
333
  
334
  # Log cluster state changes at DEBUG level
335
  debug {
336
    verbose-gossip-logging = off
337
    verbose-heartbeat-logging = off
338
  }
339
}
340
```
341

342
### JMX Monitoring
343

344
```hocon
345
akka.cluster {
346
  # Enable JMX monitoring
347
  jmx.enabled = on
348
  
349
  # Cluster MBean name
350
  jmx.multi-mbeans-in-same-jvm = on
351
}
352
```
353

354
### Metrics Publication
355

356
```hocon
357
akka.cluster {
358
  # Publish cluster metrics for monitoring
359
  metrics {
360
    enabled = on
361
    native-library-extract-folder = ${user.dir}/target/native
362
    
363
    # How often metrics are sampled
364
    sample-interval = 3s
365
    
366
    # How often metrics are gossiped
367
    gossip-interval = 3s
368
    
369
    # Metrics moving average window
370
    moving-average-half-life = 12s
371
  }
372
}
373
```
374

375
## Advanced Configuration
376

377
### Scheduler Configuration
378

379
```hocon
380
akka.cluster {
381
  # Use dedicated scheduler for cluster operations
382
  use-dispatcher = "akka.cluster.cluster-dispatcher"
383
  
384
  # Cluster scheduler tick duration
385
  scheduler {
386
    tick-duration = 33ms
387
    ticks-per-wheel = 512
388
  }
389
}
390

391
akka.cluster.cluster-dispatcher {
392
  type = "Dispatcher"
393
  executor = "fork-join-executor"
394
  fork-join-executor {
395
    parallelism-min = 2
396
    parallelism-max = 4
397
  }
398
}
399
```
400

401
### Network Partition Handling
402

403
```hocon
404
akka.cluster {
405
  # Allow weakly up members in partitioned clusters
406
  allow-weakly-up-members = on
407
  
408
  # Quarantine unreachable members after this duration  
409
  unreachable-nodes-reaper-interval = 1s
410
  
411
  # Auto-down has been removed in Akka 2.6+
412
  # Use split-brain-resolver instead
413
}
414
```
415

416
### Cluster Formation
417

418
```hocon
419
akka.management {
420
  cluster.bootstrap {
421
    # Bootstrap method (for cloud environments)
422
    contact-point-discovery {
423
      service-name = "my-service"
424
      discovery-method = "kubernetes-api"
425
    }
426
  }
427
}
428
```
429

430
## Configuration Validation
431

432
### Config Compatibility Checking
433

434
```scala { .api }
435
trait JoinConfigCompatChecker {
436
  def check(toCheck: Config): ConfigValidation
437
}
438

439
class JoinConfigCompatCheckCluster extends JoinConfigCompatChecker
440
```
441

442
### Custom Config Validation
443

444
```scala
445
class CustomConfigChecker extends JoinConfigCompatChecker {
446
  def check(toCheck: Config): ConfigValidation = {
447
    // Custom validation logic
448
    if (toCheck.getString("app.database-version") == expectedVersion) {
449
      Valid
450
    } else {
451
      Invalid("Database version mismatch")
452
    }
453
  }
454
}
455
```
456

457
```hocon
458
akka.cluster.configuration-compatibility-check {
459
  checkers = ["com.example.CustomConfigChecker"]
460
}
461
```
462

463
## Environment-Specific Configuration
464

465
### Development
466

467
```hocon
468
akka.cluster {
469
  seed-nodes = ["akka://dev@127.0.0.1:2551"]
470
  min-nr-of-members = 1
471
  log-info = on
472
  log-info-verbose = on
473
}
474
```
475

476
### Production
477

478
```hocon
479
akka.cluster {
480
  seed-nodes = [
481
    "akka://prod@node1.example.com:2551",
482
    "akka://prod@node2.example.com:2551", 
483
    "akka://prod@node3.example.com:2551"
484
  ]
485
  min-nr-of-members = 3
486
  log-info = on
487
  log-info-verbose = off
488
  
489
  failure-detector.threshold = 12.0
490
  gossip-interval = 1s
491
  
492
  split-brain-resolver {
493
    active-strategy = "keep-majority"
494
    stable-after = 30s
495
  }
496
}
497
```
498

499
### Docker/Kubernetes
500

501
```hocon
502
akka {
503
  cluster {
504
    seed-nodes = []  # Use Cluster Bootstrap instead
505
  }
506
  
507
  management {
508
    cluster.bootstrap {
509
      contact-point-discovery {
510
        service-name = ${?SERVICE_NAME}
511
        discovery-method = "kubernetes-api"
512
      }
513
    }
514
  }
515
  
516
  discovery {
517
    kubernetes-api {
518
      pod-label-selector = "app=%s"
519
    }
520
  }
521
}
522
```