0
# Configuration and Settings
1

2
ClusterShardingSettings provides comprehensive configuration for tuning sharding behavior, performance, and operational characteristics. It supports both programmatic configuration and configuration file-based setup.
3

4
## Creating Settings
5

6
### From Actor System
7

8
Use default configuration from `akka.cluster.sharding`:
9

10
```scala { .api }
11
object ClusterShardingSettings {
12
  def apply(system: ActorSystem): ClusterShardingSettings
13
}
14
```
15

16
**Usage Example:**
17
```scala
18
val settings = ClusterShardingSettings(system)
19
```
20

21
### From Config
22

23
Create settings from a custom configuration:
24

25
```scala { .api }
26
def apply(config: Config): ClusterShardingSettings
27
```
28

29
**Usage Example:**
30
```scala
31
val config = system.settings.config.getConfig("my-sharding")
32
val settings = ClusterShardingSettings(config)
33
```
34

35
## Core Configuration Properties
36

37
### Basic Settings
38

39
```scala { .api }
40
class ClusterShardingSettings(
41
  role: Option[String],
42
  rememberEntities: Boolean,
43
  journalPluginId: String,
44
  snapshotPluginId: String,
45
  stateStoreMode: String,
46
  rememberEntitiesStore: String,
47
  passivationStrategy: PassivationStrategy,
48
  shardFailureBackoff: FiniteDuration,
49
  entityRestartBackoff: FiniteDuration,
50
  rebalanceInterval: FiniteDuration,
51
  snapshotAfter: Int,
52
  keepNrOfBatches: Int,
53
  leastShardAllocationRebalanceThreshold: Int,
54
  leastShardAllocationMaxSimultaneousRebalance: Int,
55
  waitingForStateTimeout: FiniteDuration,
56
  updatingStateTimeout: FiniteDuration,
57
  coordinatorSingletonSettings: ClusterSingletonManagerSettings,
58
  coordinatorSingletonRole: Option[String],
59
  usePassivateIdleEntities: Boolean,
60
  tuningParameters: TuningParameters,
61
  coordinatorStateWriteMajorityPlus: Int,
62
  coordinatorStateReadMajorityPlus: Int,
63
  leastShardAllocationAbsoluteLimit: Int,
64
  leastShardAllocationRelativeLimit: Double
65
)
66
```
67

68
### State Store Modes
69

70
```scala { .api }
71
object ClusterShardingSettings {
72
  val StateStoreModePersistence = "persistence"
73
  val StateStoreModeDData = "ddata"
74
}
75
```
76

77
- **`StateStoreModePersistence`**: Use Akka Persistence for state storage (deprecated)
78
- **`StateStoreModeDData`**: Use Akka Distributed Data for state storage (recommended)
79

80
### Remember Entities Store Types
81

82
```scala { .api }
83
private[akka] val RememberEntitiesStoreDData = "ddata"
84
private[akka] val RememberEntitiesStoreEventsourced = "eventsourced"
85
private[akka] val RememberEntitiesStoreCustom = "custom"
86
```
87

88
## Tuning Parameters
89

90
### Core Tuning Parameters Class
91

92
```scala { .api }
93
class TuningParameters(
94
  coordinatorFailureBackoff: FiniteDuration,
95
  retryInterval: FiniteDuration,
96
  bufferSize: Int,
97
  handOffTimeout: FiniteDuration,
98
  shardStartTimeout: FiniteDuration,
99
  shardFailureBackoff: FiniteDuration,
100
  entityRestartBackoff: FiniteDuration,
101
  rebalanceInterval: FiniteDuration,
102
  snapshotAfter: Int,
103
  keepNrOfBatches: Int,
104
  leastShardAllocationRebalanceThreshold: Int,
105
  leastShardAllocationMaxSimultaneousRebalance: Int,
106
  waitingForStateTimeout: FiniteDuration,
107
  updatingStateTimeout: FiniteDuration,
108
  entityRecoveryStrategy: String,
109
  entityRecoveryConstantRateStrategyFrequency: FiniteDuration,
110
  entityRecoveryConstantRateStrategyNumberOfEntities: Int,
111
  coordinatorStateWriteMajorityPlus: Int,
112
  coordinatorStateReadMajorityPlus: Int,
113
  leastShardAllocationAbsoluteLimit: Int,
114
  leastShardAllocationRelativeLimit: Double,
115
  passivationStopTimeout: FiniteDuration
116
)
117
```
118

119
### Key Tuning Parameters
120

121
- **`coordinatorFailureBackoff`**: Backoff when coordinator fails (default: 5s)
122
- **`retryInterval`**: Interval for retrying failed operations (default: 2s)
123
- **`bufferSize`**: Message buffer size for pending operations (default: 1000)
124
- **`handOffTimeout`**: Timeout for shard handoff during rebalancing (default: 10s)
125
- **`shardStartTimeout`**: Timeout for starting new shards (default: 10s)
126
- **`rebalanceInterval`**: Interval between rebalancing attempts (default: 10s)
127
- **`snapshotAfter`**: Number of changes before taking snapshot (default: 1000)
128

129
## Passivation Strategy Settings
130

131
### Passivation Strategy Configuration
132

133
```scala { .api }
134
class PassivationStrategySettings(
135
  strategy: PassivationStrategy,
136
  idleEntitySettings: Option[IdleSettings],
137
  oldestEntitySettings: Option[OldestSettings],
138
  mostRecentlyUsedEntitySettings: Option[MostRecentlyUsedSettings],
139
  leastRecentlyUsedEntitySettings: Option[LeastRecentlyUsedSettings],
140
  leastFrequentlyUsedEntitySettings: Option[LeastFrequentlyUsedSettings]
141
)
142
```
143

144
### Idle-based Passivation
145

146
```scala { .api }
147
class IdleSettings(
148
  timeout: FiniteDuration,
149
  interval: FiniteDuration
150
)
151
```
152

153
**Configuration Example:**
154
```hocon
155
akka.cluster.sharding {
156
  passivation {
157
    strategy = idle
158
    idle-entity {
159
      timeout = 2m
160
      interval = 1m
161
    }
162
  }
163
}
164
```
165

166
### Age-based Passivation Strategies
167

168
```scala { .api }
169
class OldestSettings(
170
  segmentSize: Int,
171
  proportionToPassivatePerRebalance: Double,
172
  idleTimeBeforeCleanUp: FiniteDuration
173
)
174

175
class LeastRecentlyUsedSettings(
176
  segmentSize: Int,
177
  proportionToPassivatePerRebalance: Double,
178
  idleTimeBeforeCleanUp: FiniteDuration
179
)
180

181
class MostRecentlyUsedSettings(
182
  segmentSize: Int,
183
  proportionToPassivatePerRebalance: Double,
184
  idleTimeBeforeCleanUp: FiniteDuration
185
)
186

187
class LeastFrequentlyUsedSettings(
188
  segmentSize: Int,
189
  proportionToPassivatePerRebalance: Double,
190
  idleTimeBeforeCleanUp: FiniteDuration
191
)
192
```
193

194
## Settings Builder Methods
195

196
### Role Configuration
197

198
```scala { .api }
199
def withRole(role: String): ClusterShardingSettings
200
def withRole(role: Option[String]): ClusterShardingSettings
201
```
202

203
**Usage Example:**
204
```scala
205
val settings = ClusterShardingSettings(system)
206
  .withRole("worker")
207
```
208

209
### Remember Entities Configuration
210

211
```scala { .api }
212
def withRememberEntities(rememberEntities: Boolean): ClusterShardingSettings
213
```
214

215
### State Store Configuration
216

217
```scala { .api }
218
def withStateStoreMode(mode: String): ClusterShardingSettings
219
```
220

221
### Passivation Configuration
222

223
```scala { .api }
224
def withPassivationStrategy(strategy: PassivationStrategy): ClusterShardingSettings
225
```
226

227
## Configuration File Example
228

229
Complete configuration example in `application.conf`:
230

231
```hocon
232
akka.cluster.sharding {
233
  # Number of shard regions that must be available for the coordinator
234
  # to continue processing commands
235
  waiting-for-state-timeout = 5s
236
  
237
  # Timeout for updating distributed state (write/read)
238
  updating-state-timeout = 5s
239
  
240
  # The shard region for a entity type can be started on nodes filtered by role
241
  role = "worker"
242
  
243
  # When 'remember-entities' is enabled the Shard will automatically restart
244
  # entities that were previously running in the shard
245
  remember-entities = off
246
  
247
  # Set this to a time duration to have sharding passivate entities when they have not
248
  # received any message in this length of time
249
  passivation {
250
    strategy = idle
251
    idle-entity {
252
      timeout = 2m
253
      interval = 1m
254
    }
255
  }
256
  
257
  # Rebalancing is performed periodically based on this interval
258
  rebalance-interval = 10s
259
  
260
  # Absolute limit of how many shards the rebalance algorithm will rebalance
261
  # in one rebalance round
262
  least-shard-allocation-strategy.rebalance-absolute-limit = 20
263
  
264
  # Relative limit of how many shards the rebalance algorithm will rebalance
265
  # in one rebalance round.
266
  least-shard-allocation-strategy.rebalance-relative-limit = 0.1
267
  
268
  # The coordinator saves persistent snapshots after this number of changes
269
  snapshot-after = 1000
270
  
271
  # Setting for the default shard allocation strategy
272
  tuning {
273
    coordinator-failure-backoff = 5s
274
    retry-interval = 2s
275
    buffer-size = 1000
276
    handoff-timeout = 10s
277
    shard-start-timeout = 10s
278
    shard-failure-backoff = 10s
279
    entity-restart-backoff = 10s
280
    rebalance-interval = 10s
281
    snapshot-after = 1000
282
    keep-nr-of-batches = 2
283
  }
284
  
285
  # Settings for the coordinator singleton
286
  coordinator-singleton = ${akka.cluster.singleton}
287
  
288
  # Settings for remember entities store when using ddata
289
  distributed-data {
290
    # minCap parameter to MajorityWrite and MajorityRead consistency level
291
    majority-min-cap = 5
292
    durable.keys = ["shard-*"]
293
    
294
    # When using many entities with "remember entities" the Gossip message
295
    # can become to large if including to many in same message. Limit to 10 entries.
296
    max-delta-elements = 10
297
  }
298
}
299
```
300

301
## Advanced Configuration
302

303
### Coordinator Singleton Settings
304

305
```scala { .api }
306
coordinatorSingletonSettings: ClusterSingletonManagerSettings
307
coordinatorSingletonRole: Option[String]
308
```
309

310
### Entity Recovery Strategy
311

312
Control how entities are recovered when remember-entities is enabled:
313

314
- **`"all"`**: Recover all entities immediately (default)
315
- **`"constant"`**: Recover entities at a constant rate
316

317
### Lease Integration
318

319
```scala { .api }
320
useLeaseForRebalancing: Boolean
321
leaseSettings: Option[LeaseUsageSettings]
322
```
323

324
## Settings Validation
325

326
The settings are validated on creation:
327
- Timeouts must be positive
328
- Buffer sizes must be positive
329
- Percentages must be between 0.0 and 1.0
330
- Required fields must be present