Merge pull request #166 from akka/main

docs: publish latest updates

Makefile

@@ -44,7 +44,7 @@ attributes: prepare
 		> "${managed_partials}/attributes.adoc"
 	docs/bin/version.sh | xargs -0  printf ":akka-javasdk-version: %s" \
 		> "${managed_partials}/attributes.adoc"
-	echo ":akka-cli-version: 3.0.8"     >> "${managed_partials}/attributes.adoc"
+	echo ":akka-cli-version: 3.0.10"     >> "${managed_partials}/attributes.adoc"
 	echo ":akka-cli-min-version: 3.0.4" >> "${managed_partials}/attributes.adoc"
 	# see https://adoptium.net/marketplace/
 	echo ":java-version: 21" \

docs/src/modules/concepts/pages/multi-region.adoc

@@ -16,40 +16,48 @@ Multi-region operations are ideal for:
 * Low latency global reads
 * Low latency global writes
 
-== Examples
+== Replicated reads
 
-The two main replication strategies that Akka offers are replicated reads, and replicated writes.
-
-=== Replicated reads
-
-With replicated reads, an entity has its "home" in one primary region, while being replicated to multiple other regions.
+Akka's replicated reads offers full data replication across regions and even cloud providers, without any changes to the service implementation: an entity has its "home" in one _primary region_, while being replicated to multiple other regions.
 
 image:geo-a.svg[Geo data replication, width=600]
 
-In the example above, the entity representing Alice has its primary region in Los Angeles (USA). When a user in the primary region performs a read request, the request is handled locally, and the response sent straight back.
+In the image above, the entity representing Alice has its primary region in Los Angeles. When a user A in the primary region performs a read request image:steps-1.svg[width=20], the request is handled locally, and the response sent straight back image:steps-2.svg[width=20].
+
+When the user in the primary region performs a write request image:steps-1.svg[width=20], that request is also handled locally, and a response sent directly back image:steps-2.svg[width=20]. After that write request completes, that write is replicated to other regions image:steps-3.svg[width=20], such as in London (UK).
 
-When the user in the primary region performs a write request, that request is also handled locally, and a response sent directly back. After that write request completes, that write is replicated to other regions, such as in London (UK). A user in London, when they perform a read, that read operation will happen locally, and a response sent immediately back.
+A user B in London, when they perform a read image:steps-4.svg[width=20], that read operation will happen locally, and a response sent immediately back image:steps-5.svg[width=20].
 
 A user can also perform write operations on entities in non-primary regions.
 
 image:geo-b.svg[Geo data replication, width=600]
 
-In this scenario, a user in London (UK) is performing a write operation on the Alice entity. Since London is not the primary region for the Alice entity, Akka will automatically forward that request to the primary region, in this case, Los Angeles (USA). That request will be handled in the USA, and a response sent directly back to the user.
-
-Akka has a configurable primary selection mode. The two main modes are static, and dynamic. In the static primary selection mode, the primary region for an entity is selected statically as part of the deployment, so all entities have the same primary region. This is useful for scenarios where you want one primary region, with the ability to failover to another region in the case of a regional outage.
-
-In the dynamic primary selection mode, each entity can have a different region that is considered its primary region. This is selected based on whichever region the entity was first written in. This is useful for scenarios where you want to have the primary region for you data close to the users who use the data. A user, Alice, in the USA, will have her data in the USA, while a user Bob, in the UK, will have his data, in the UK.
+In this scenario, the user B in London (UK) is performing a write operation on the Alice entity image:steps-1.svg[width=20]. Since London is not the primary region for the Alice entity, Akka will automatically forward that request to the primary region image:steps-2.svg[width=20], in this case, Los Angeles (USA). That request will be handled in the USA, and a response sent directly back to the user image:steps-3.svg[width=20].
 
 image:geo-c.svg[Geo data replication, width=600]
 
-When Bob makes a request in the UK on his data, that request is handled locally, and replicated to the US, while Alice's requests in the USA with her data are handled locally in the USA, and replicated to the UK.
+When Bob makes a request in the UK on his data image:steps-1.svg[width=20], that request is handled locally image:steps-2.svg[width=20], and replicated to the US image:steps-3.svg[width=20]. Exactly the same as Alice's requests in the USA with her data are handled locally in the USA, and replicated to the UK.
 
-The data however is still available in all regions. If Bob travels to the USA, he can still access his data.
+The data however is still available in all regions. If Bob travels to the USA, he can access his data in the Los Angeles region.
 
 image:geo-d.svg[Geo data replication, width=600]
 
-When Bob travels to the USA, read requests that Bob makes on his data are handled locally, while write requests are forwarded to the UK. Meanwhile, write requests made by Alice on her data is all handled locally, with writes being replicated to the UK.
+When Bob travels to the USA, read requests that Bob makes on his data are handled locally image:steps-1.svg[width=20] and getting an immediate reply image:steps-3.svg[width=20]. Write requests, on the other hand, are forwarded to the UK image:steps-2.svg[width=20], before the reply is sent image:steps-3.svg[width=20].
+
+image:geo-e.svg[Geo data replication, width=600]
+
+Meanwhile, all requests made by Alice on her data are handled locally image:steps-1.svg[width=20] and get an immediate reply image:steps-2.svg[width=20]. The write operations are being replicated to the UK image:steps-3.svg[width=20].
+
+=== Primary selection
+
+How Akka assigns the primary region to an entity is configurable. The two main modes are **static**, and **dynamic**.
+
+In the **static primary selection** mode (which is the default), the primary region for an entity is selected statically as part of the deployment, so all entities have the same primary region. This is useful for scenarios where you want one primary region, with the ability to fail over to another region in the case of a regional outage.
+
+In the **dynamic primary selection** mode, each entity can have a different region that is considered its primary region. This is selected based on whichever region the entity was first written in. This is useful for scenarios where you want to have the primary region for you data close to the users who use the data. A user, Alice, in the USA, will have her data in the USA, while a user Bob, in the UK, will have his data, in the UK.
+
+The Operating section explains more details about xref:operations:regions/index.adoc#selecting-primary[configuring the primary selection mode].
 
-=== Replicated writes
+== Replicated writes
 
 The replicated write replication strategy allows every region to be capable of handling writes for all entities. This is done through the use of CRDTs, which can be modified concurrently in different regions, and their changes safely merged without conflict.

docs/src/modules/operations/pages/regions/index.adoc

@@ -38,7 +38,7 @@ When you deploy a service it will run in all regions of the project. When you ad
 [[selecting-primary]]
 === Selecting primary for stateful components
 
-Stateful components like Event Sourced Entities or Workflow can be replicated to other regions. For each stateful component instance there is a primary region, which handles all write requests. Read requests can be served from any region. See xref:java:event-sourced-entities.adoc#_replication[Event Sourced Entity replication] and xref:java:workflows.adoc#_replication[Workflow replication] for more information about read and write requests.
+Stateful components like Event Sourced Entities and Workflows can be replicated to other regions. For each stateful component instance there is a primary region, which handles all write requests. Read requests can be served from any region. See xref:java:event-sourced-entities.adoc#_replication[Event Sourced Entity replication] and xref:java:workflows.adoc#_replication[Workflow replication] for more information about read and write requests.
 
 There are two operational choices for deciding where the primary is located: