Merge pull request #155 from akka/main

Merge main to java-spi

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.9"     >> "${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,44 @@ 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 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 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, a user 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], while 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.
 
 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], while write requests are forwarded to the UK image:steps-2.svg[width=20]. Meanwhile, write requests made by Alice on her data is all handled locally image:steps-4.svg[width=20] image:steps-5.svg[width=20], with writes being replicated to the UK image:steps-6.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/services/deploy-service.adoc

@@ -30,7 +30,7 @@ The docker build output in maven will print something similar to the following:
 ----
 DOCKER> Tagging image shopping-cart:1.0-SNAPSHOT-20241028102843 successful!
 ----
-
+[#_deploying_a_service]
 == Deploying a service
 
 Services can be deployed via the Akka CLI.
@@ -171,16 +171,17 @@ For further details, see xref:operations:projects/external-container-registries.
 [#apply]
 == Using service descriptors
 
-Akka services can also be described and managed with *YAML service descriptors*.
+Akka services can also be described and managed with *YAML service descriptors*. See xref:reference:descriptors/service-descriptor.adoc[].
 
-First, <<_build_container_image>> and then push the image:
+You can deploy your service using a service descriptor.
+For this you need at least the image, which you can get by <<_build_container_image, building the container image>> and then <<_pushing_to_acr, pushing it to the container registry>>:
 
 [source, command line]
 ----
 akka container-registry push container-name:tag-name
 ----
 
-Example of service descriptor:
+Once pushed, you need to use the suggested image from the command's output in your service descriptor, for example:
 
 [source, yaml]
 ----
@@ -192,7 +193,7 @@ spec:
     value: some value
 ----
 
-NOTE: You must add the primary region image tag. See `akka container-registry push` command's output.
+NOTE: You must add the primary region image tag from `akka container-registry push` output.
 
 To apply this descriptor, run:
 
@@ -216,6 +217,15 @@ After editing the service descriptor (e.g., `my-service.yaml`), redeploy it with
 akka service apply -f my-service.yaml
 ----
 
+=== Editing the service descriptor in place
+
+Once you have <<_deploying_a_service, deployed your service>>, you can also modify it by editing its service descriptor:
+
+[source, command line]
+----
+akka service edit my-service
+----
+
 == Removing a deployed service
 
 To delete a service and free its resources, run the following command, replacing `my-service` with the name of the service you want to remove:
@@ -245,3 +255,4 @@ You now know how to deploy, verify, update, and remove Akka services using the A
 == Related documentation
 
 - xref:reference:cli/akka-cli/akka_services.adoc[`akka service` CLI commands]
+- xref:reference:descriptors/service-descriptor.adoc[Akka Service Descriptor]