diff --git a/akka-cluster-sharding-typed/src/main/resources/reference.conf b/akka-cluster-sharding-typed/src/main/resources/reference.conf index 756c3f0876..1c311574de 100644 --- a/akka-cluster-sharding-typed/src/main/resources/reference.conf +++ b/akka-cluster-sharding-typed/src/main/resources/reference.conf @@ -1,4 +1,6 @@ +# //#sharding-ext-config +# //#number-of-shards akka.cluster.sharding { # Number of shards used by the default HashCodeMessageExtractor # when no other message extractor is defined. This value must be @@ -7,6 +9,8 @@ akka.cluster.sharding { # stopping all nodes in the cluster. number-of-shards = 1000 } +# //#number-of-shards +# //#sharding-ext-config akka.cluster.configuration-compatibility-check.checkers { akka-cluster-sharding-hash-extractor = "akka.cluster.sharding.typed.internal.JoinConfigCompatCheckerClusterSharding" diff --git a/akka-docs/src/main/paradox/cluster-sharding.md b/akka-docs/src/main/paradox/cluster-sharding.md index 6f6a7e1a01..c92ea464c7 100644 --- a/akka-docs/src/main/paradox/cluster-sharding.md +++ b/akka-docs/src/main/paradox/cluster-sharding.md @@ -81,7 +81,7 @@ be the same. Otherwise the entity actor might accidentally be started in several Creating a good sharding algorithm is an interesting challenge in itself. Try to produce a uniform distribution, i.e. same amount of entities in each shard. As a rule of thumb, the number of shards should be a factor ten greater -than the planned maximum number of cluster nodes. Less shards than number of nodes will result in that some nodes +than the planned maximum number of cluster nodes. Fewer shards than number of nodes will result in that some nodes will not host any shards. Too many shards will result in less efficient management of the shards, e.g. rebalancing overhead, and increased latency because the coordinator is involved in the routing of the first message for each shard. The sharding algorithm must be the same on all nodes in a running cluster. It can be changed after stopping diff --git a/akka-docs/src/main/paradox/typed/cluster-sharding-concepts.md b/akka-docs/src/main/paradox/typed/cluster-sharding-concepts.md index e9b40a5bcf..8beb682aa4 100644 --- a/akka-docs/src/main/paradox/typed/cluster-sharding-concepts.md +++ b/akka-docs/src/main/paradox/typed/cluster-sharding-concepts.md @@ -60,7 +60,7 @@ the oldest member among all cluster nodes or a group of nodes tagged with a spec role. The logic that decides where a shard is to be located is defined in a -pluggable @ref:[shard allocation strategy](cluster-sharding.md#shard-allocation-strategy). +pluggable @ref:[shard allocation strategy](cluster-sharding.md#shard-allocation). ### Shard rebalancing diff --git a/akka-docs/src/main/paradox/typed/cluster-sharding.md b/akka-docs/src/main/paradox/typed/cluster-sharding.md index 4d7eb5384b..155aa0cb69 100644 --- a/akka-docs/src/main/paradox/typed/cluster-sharding.md +++ b/akka-docs/src/main/paradox/typed/cluster-sharding.md @@ -124,16 +124,34 @@ is used but `tell` or any of the other @ref:[Interaction Patterns](interaction-p See @ref:[persistence](persistence.md) for more details. -## Shard allocation strategy +## Shard allocation -The default implementation `akka.cluster.sharding.ShardCoordinator.LeastShardAllocationStrategy` -allocates new shards to the `ShardRegion` with least number of previously allocated shards. +A shard is a group of entities that will be managed together. The grouping is typically defined by a hashing +function of the `entityId`. For a specific entity identifier the shard identifier must always +be the same. Otherwise the entity actor might accidentally be started in several places at the same time. + +By default the shard identifier is the absolute value of the `hashCode` of the entity identifier modulo +the total number of shards. The number of shards is configured by: + +@@snip [reference.conf](/akka-cluster-sharding-typed/src/main/resources/reference.conf) { #number-of-shards } + +As a rule of thumb, the number of shards should be a factor ten greater than the planned maximum number of +cluster nodes. It doesn't have to be exact. Fewer shards than number of nodes will result in that some nodes will +not host any shards. Too many shards will result in less efficient management of the shards, e.g. rebalancing overhead, +and increased latency because the coordinator is involved in the routing of the first message for each +shard. + +The `number-of-shards` configuration value must be the same for all nodes in the cluster and that is verified by +configuration check when joining. Changing the value requires stopping all nodes in the cluster. + +The shards are allocated to the nodes in the cluster. The decision of where to allocate a shard is done +by a shard allocation strategy. The default implementation `akka.cluster.sharding.ShardCoordinator.LeastShardAllocationStrategy` +allocates new shards to the `ShardRegion` (node) with least number of previously allocated shards. This strategy can be replaced by an application specific implementation. An optional custom shard allocation strategy can be passed into the optional parameter when initializing an entity type or explicitly using the `withAllocationStrategy` function. -See the API documentation of @scala[`akka.cluster.sharding.ShardAllocationStrategy`]@java[`akka.cluster.sharding.AbstractShardAllocationStrategy`] for details -of how to implement a custom `ShardAllocationStrategy`. +See the API documentation of @scala[`akka.cluster.sharding.ShardAllocationStrategy`]@java[`akka.cluster.sharding.AbstractShardAllocationStrategy`] for details of how to implement a custom `ShardAllocationStrategy`. ## How it works @@ -374,4 +392,8 @@ properties are read by the `ClusterShardingSettings` when created with an ActorS It is also possible to amend the `ClusterShardingSettings` or create it from another config section with the same layout as below. +One important configuration property is `number-of-shards` as described in @ref:[Shard allocation](#shard-allocation) + @@snip [reference.conf](/akka-cluster-sharding/src/main/resources/reference.conf) { #sharding-ext-config } + +@@snip [reference.conf](/akka-cluster-sharding-typed/src/main/resources/reference.conf) { #sharding-ext-config }