Shard region

As explained in Akka in Action, Second Edition

A shard region is an Akka Cluster Sharding component on a node that routes messages to entities and contains or communicates with shards.

A shard region is the message-routing boundary for sharded entities on a cluster node. It contains shards, and each shard groups entities according to the configured sharding function. Applications send entity messages through a shard region rather than needing to locate or spawn the target actor themselves. section 9.1.1 section 9.1.2

Figure 9.1 Relationships among nodes, shared regions, shards, and entities

Use this diagram to distinguish the containment hierarchy: nodes host shard regions, shard regions contain shards, and shards contain distributed entities. section 9.1.1

A shard region makes several distributed behaviors practical:

• Routes a local message to the entity’s hosting region when that entity lives on another node. section 9.1.1
• Consults the shard coordinator when it does not know an entity location; the coordinator then shares the discovered region information with all shard regions. section 9.1.1
• Lets an entity be addressed by an EntityTypeKey and string ID, with different entity types allowed to reuse the same ID. section 9.1.2
• Causes a missing entity to be created when a message is sent to it, while exposing an EntityRef-style API rather than a direct ActorRef. section 9.1.2

Route cargo commands to a container

Initialize ClusterSharding with a Container entity definition, deriving the behavior’s containerId from EntityContext.entityId. The returned shard-region ActorRef accepts ShardingEnvelope values: wrapping "id-1" with AddCargo routes the command and creates that container if needed. EntityContext supplies the entity type key and ID, not ActorContext features such as watching, logging, spawning, or scheduling. section 9.1.2

Expose a sharded entity through gRPC

A market service initializes a shard region, obtains an EntityRef with entityRefFor using the market ID, and calls entityRef.ask to turn a GetState request into a response. This is appropriate outside an actor context; actor-internal requests instead use context.ask to preserve actor-state consistency. section 12.2.1

A shard region also distinguishes Akka Cluster Sharding from ShardedDaemonProcess. Both distribute behaviors, but the region acts as a proxy for direct actor messaging. ShardedDaemonProcess has a fixed instance count at creation and no equivalent direct-message proxy. section 10.3.3

How Akka in Action, Second Edition covers it

How deep it goes

Explains region containment, coordinator-assisted lookup, forwarding, initialization, envelopes, and EntityRef use; defers split-brain handling details.

Examples

Demonstrates container cargo routing and a gRPC market service that obtains an EntityRef and asks for market state.

What it assumes

Builds from actor protocols and identifiers while distinguishing EntityContext from ActorContext capabilities.

What you can do after

Apply it via Akka Cluster Sharding to initialize a region, envelope entity commands, and request entities by typed ID.

How it connects

Connects shard regions with shards, entities, shard coordinator, EntityTypeKey, EntityRef, ShardingEnvelope, and ShardedDaemonProcess.

liveBookmanning.com

Read Akka in Action, Second Edition on liveBook Get the book at manning.com

Related concepts

• dataset splithas part · A dataset split is the division of a dataset into distinct subsets assigned different purposes, such as training, validation, or testing.
• entityuses · A sharding entity is an actor instance identified and placed by cluster sharding, with at most one instance active in the cluster.
• cluster shardingused by · Cluster sharding is an Akka technique that distributes actors across cluster nodes according to a partition key.
• EntityTypeKeyconfigured by · EntityTypeKey is an Akka Cluster Sharding identifier that represents an entity type and is used to create or address sharded entities.

This explainer was generated by Manning's knowledge graph from the text of Akka in Action, Second Edition. The section links point to the parts of the book it draws on.