Skip to content
English

Allocation strategy

The sharding coordinator picks a node for each shard:

  • At first contact — when a shard ID appears for the first time, the coordinator runs allocate(shardId, candidates, currentShards) to pick its owner.
  • On rebalance — every few seconds, the coordinator runs rebalance(currentShards, candidates, inProgress) to find shards that should move.

The two built-in strategies trade simplicity for balance:

StrategyAllocationRebalance
HashAllocationStrategy (default)shardId mod sorted-candidatesOnly when the set of candidates that are up changes, once that change has settled — but then most shards at once.
LeastShardAllocationStrategyCandidate with fewest shards.Drains the busiest node into the rest.
import { HashAllocationStrategy, StartShardingOptions } from 'actor-ts/cluster';
const startShardingOptions = StartShardingOptions.create()
.withTypeName('cart')
.withEntityActor(CartActor)
.withExtractEntityId((message) => message.entityId)
.withAllocationStrategy(new HashAllocationStrategy());
sharding.start(
startShardingOptions, // default
);

The formula:

const sorted = [...candidates].sort();
return sorted[shardId % sorted.length];

Picks:

  • Deterministic — given the same candidate set, same shards always land on same nodes.
  • Minimal rebalance — only shards whose hash-target changes need to move (when nodes join or leave). “Minimal” is relative to doing it at all, not to how much moves: the modulus changes for most shards when the candidate count does, so at numShards = 64 a 1 → 2 join re-homes 32 shards, a 2 → 3 join 42 to 44 and a 3 → 4 join 46 to 49. The range is address order at work: the candidates are sorted, so the figure depends on where the new node sorts — the low end when it sorts last, the high end when it sorts first. The strategy proposes all of them in one pass; what keeps that from arriving as one burst is the coordinator’s own ceiling — see the ceiling on churn.
  • Zero state — the strategy doesn’t track anything; it’s a pure function.

Doesn’t:

  • Balance by load — uneven entity activity means some nodes end up busier than others, even with the same shard count.
  • Compensate for slow nodes — a struggling member still gets its fair share of shards.

Right for uniform workloads where shards are roughly equal in cost, or as a sensible default while you measure whether you need something smarter.

import { LeastShardAllocationStrategy, StartShardingOptions } from 'actor-ts/cluster';
const shardingOptions = StartShardingOptions.create()
// ...
.withAllocationStrategy(new LeastShardAllocationStrategy(
/* rebalanceThreshold */ 1,
/* maxSimultaneousRebalance */ 3,
));
sharding.start(shardingOptions);

The formula:

  • Allocate: pick the candidate with the fewest shards currently hosted (ties broken by address order).
  • Rebalance: first, every shard on a node that is no candidate — a region refused over its shard count, or on a member without the type’s role — whatever the candidates’ spread. Then, if max(shardCount) - min(shardCount) >= rebalanceThreshold among the candidates, move shards off the busiest node(s) to the least. At most maxSimultaneousRebalance shards per pass, both kinds together.

Picks:

  • Converges to balance even when nodes have joined / left unevenly.
  • Throttled rebalance — bounded per-pass moves avoid thrashing.
  • Address-tiebreak — deterministic ordering with no surprises.

Doesn’t:

  • Know about per-shard load — it counts shards, not work. Two shards holding very different amounts of work look the same.
  • React instantly — maxSimultaneousRebalance caps the per-pass movement; in a 100-shard cluster gaining a new node, full rebalance takes ~33 passes (×rebalanceInterval — typically a minute or so).
new LeastShardAllocationStrategy(
/* rebalanceThreshold */ 2, // trigger only when imbalance ≥ 2
/* maxSimultaneousRebalance */ 5, // up to 5 shards move per pass
);
  • rebalanceThreshold — bigger value = less churn, more tolerance for imbalance. 1 makes any imbalance trigger a rebalance; 5 waits for a real difference.
  • maxSimultaneousRebalance — bigger value = faster convergence, more handoff traffic. 3 is a reasonable middle.

This cap and the configured rebalance ceiling are two different levels and both apply: maxSimultaneousRebalance bounds what this strategy proposes per pass, the ceiling bounds what the coordinator accepts from any strategy. A strategy that caps itself is therefore not a substitute for the ceiling — the default one caps nothing, and neither does one you write.

For 100-shard clusters with frequent membership churn, raise both (threshold ~3, max ~10). For 16-shard clusters where each shard move is expensive (large state), keep them low.

Implement the interface:

interface AllocationStrategy {
allocate(
shardId: number,
candidates: ReadonlyArray<NodeAddress>,
currentShards: ReadonlyMap<string, ReadonlySet<number>>,
): NodeAddress;
rebalance(
currentShards: ReadonlyMap<string, ReadonlySet<number>>,
candidates: ReadonlyArray<NodeAddress>,
rebalanceInProgress: ReadonlySet<number>,
): Set<number>;
}

The coordinator never places a shard on a region whose member is not up, and it tracks how long the set of regions whose member is up — the eligible regions — has held still (see members that are not up). That decides how your strategy is called:

  • While the set is settling, allocate may be asked twice for one shard: first with every registered region that could host the type and the shards every registered region holds — where the shard would go with everyone in view — and, only when it picks one whose member is not up, again with the eligible regions alone and their shards. rebalance is not called at all.
  • Once the set has held still for the settle window, allocate is asked once, with the eligible regions and their shards, and rebalance is called with the eligible regions as candidates and the shards of every region whose member is up. That map is wider than the candidates on purpose: it also lists a region registered on an up member that is no candidate — refused over its shard count, or without the type’s role — so that its shards can be proposed for a move onto a candidate. Both built-in strategies propose every one of them — LeastShardAllocationStrategy ahead of its threshold check, within its per-pass budget. A custom strategy that weighs only the candidates leaves them where they are.

Either way a pick that is not among the candidates the call was given is never placed — the coordinator logs it at WARN, naming the pick and the candidates, once per shard until that shard is placed — and a rebalance proposal for a shard whose current owner is not up is dropped. So an allocate call is a question, not a placement: a strategy that keeps state — a round-robin cursor, a “last owner” — must not count one as a shard having landed anywhere.

Useful for app-specific rules:

  • Pin certain shards to certain nodes — e.g., shards with IDs < 10 always go to the coordinator-role nodes.
  • Affinity / anti-affinity — keep specific shards together, or always apart.
  • Capacity-aware — query each node’s metrics, weight by available memory.
class RoleAffinityAllocationStrategy implements AllocationStrategy {
constructor(private readonly coordinatorAddrs: Set<string>) {}
allocate(shardId, candidates, currentShards) {
if (shardId < 10) {
// Pin low-id shards to coordinator nodes
const coord = candidates.find(c => this.coordinatorAddrs.has(c.toString()));
if (coord) return coord;
}
return new HashAllocationStrategy().allocate(shardId, candidates, currentShards);
}
rebalance() { return new Set(); } // no rebalance for the example
}

The strategy runs in the coordinator, which is a singleton on the cluster leader. It must be deterministic enough that two coordinators (during a leader-change handover) would converge on the same decision — or at least not undo each other’s work.

allocate runs once per new shard ID — twice at most while membership settles — bounded by numShards (default 64). Even an expensive strategy is fine here.

rebalance runs every rebalanceIntervalMs (default 2 s) once the set of members that are up has settled. It sees the eligible regions as candidates and every shard a region on an up member holds — nothing of a region on a member that is unreachable or still joining. Keep it under 100 ms or so to avoid blocking the coordinator’s other work.

For most clusters:

  1. Default (HashAllocationStrategy) — start here. Measure.
  2. LeastShardAllocationStrategy — switch if the default produces visible hot-spots (one node CPU-saturated while others idle).
  3. Custom — only when neither built-in fits, and you have specific evidence the customization helps.

Don’t reach for a custom strategy preemptively. The built-ins cover ~95 % of use cases.