diff --git a/akka-docs/src/main/paradox/cluster-dc.md b/akka-docs/src/main/paradox/cluster-dc.md index 72c4877246..02ae066715 100644 --- a/akka-docs/src/main/paradox/cluster-dc.md +++ b/akka-docs/src/main/paradox/cluster-dc.md @@ -48,8 +48,11 @@ top of the Cluster membership information are lost. For example, it wouldn't be to use @ref[Distributed Data](distributed-data.md) across the separate clusters. We often recommend implementing a micro-service as one Akka Cluster. The external API of the -service would be HTTP or a message broker, and not Akka Remoting or Cluster, but the internal -communication within the service that is running on several nodes would use ordinary actor +service would be HTTP or a message broker, and not Akka Remoting or Cluster (see additional discussion + in the Lagom Framework docs: +@scala[[Internal and External Commmunication](https://www.lagomframework.com/documentation/current/scala/InternalAndExternalCommunication.html)] +@java[[Internal and External Communication](https://www.lagomframework.com/documentation/current/java/InternalAndExternalCommunication.html)]), +but the internal communication within the service that is running on several nodes would use ordinary actor messaging or the tools based on Akka Cluster. When deploying this service to multiple data centers it would be inconvenient if the internal communication could not use ordinary actor messaging because it was separated into several Akka Clusters. The benefit of using Akka diff --git a/akka-docs/src/main/paradox/common/cluster.md b/akka-docs/src/main/paradox/common/cluster.md index c982f7bf44..755bfdd11d 100644 --- a/akka-docs/src/main/paradox/common/cluster.md +++ b/akka-docs/src/main/paradox/common/cluster.md @@ -2,7 +2,7 @@ @@@ note -This document describes the design concepts of the clustering. +This document describes the design concepts of Akka Cluster. @@@ @@ -12,6 +12,12 @@ Akka Cluster provides a fault-tolerant decentralized peer-to-peer based cluster [membership](#membership) service with no single point of failure or single point of bottleneck. It does this using [gossip](#gossip) protocols and an automatic [failure detector](#failure-detector). +Akka cluster allows for building distributed applications, where one application or service span multiple nodes (in practice multiple `ActorSystem`s). +It is not intended as a general communication between different applications or services (for example different microservices). See the discussion on +@scala[[Internal and External Commmunication](https://www.lagomframework.com/documentation/current/scala/InternalAndExternalCommunication.html)] +@java[[Internal and External Communication](https://www.lagomframework.com/documentation/current/java/InternalAndExternalCommunication.html)] +in the docs of the [Lagom Framework](https://www.lagomframework.com) (where each microservice is an Akka Cluster) for some background on this. + ## Terms **node** diff --git a/akka-docs/src/main/paradox/common/other-modules.md b/akka-docs/src/main/paradox/common/other-modules.md index 993bbc1828..524725f554 100644 --- a/akka-docs/src/main/paradox/common/other-modules.md +++ b/akka-docs/src/main/paradox/common/other-modules.md @@ -23,3 +23,14 @@ Utilities for managing a running Akka Cluster. ## Community Projects Akka has a vibrant and passionate user community, the members of which have created many independent projects using Akka as well as extensions to it. See [Community Projects](http://akka.io/community/). + +## Related Projects Sponsored by Lightbend + +### [Play Framework](https://www.playframework.com) + +Play Framework provides a complete framework to build modern web applications, including tools for front end pipeline integration, +a HTML template language etc. It is built on top of Akka HTTP, and integrates well with Akka and Actors. + +### [Lagom](https://www.lagomframework.com) + +Lagom is a microservice framework which strives to be opinionated and encode best practices for building microservice systems with Akka and Play. \ No newline at end of file diff --git a/akka-docs/src/main/paradox/guide/tutorial_5.md b/akka-docs/src/main/paradox/guide/tutorial_5.md index f87ec690c7..a90e722706 100644 --- a/akka-docs/src/main/paradox/guide/tutorial_5.md +++ b/akka-docs/src/main/paradox/guide/tutorial_5.md @@ -251,3 +251,9 @@ To continue your journey with Akka, we recommend: * Start building your own applications with Akka, make sure you [get involved in our amazing community](http://akka.io/get-involved) for help if you get stuck. * If you’d like some additional background, read the rest of the reference documentation and check out some of the @ref:[books and videos](../additional/books.md) on Akka. + +To get from this guide to a complete application you would likely need to provide either an UI or an API. For this we recommend that you look at the following technologies and see what fits you: + + * [Akka HTTP](https://doc.akka.io/docs/akka-http/current/introduction.html) is a HTTP server and client library, making it possible to publish and consume HTTP endpoints + * [Play Framework](https://www.playframework.com) is a full fledged web framework that is built on top of Akka HTTP, it integrates well with Akka and can be used to create a complete modern web UI + * [Lagom](https://www.lagomframework.com) is an opinionated microservice framework built on top of Akka, encoding many best practices around Akka and Play diff --git a/akka-docs/src/main/paradox/howto.md b/akka-docs/src/main/paradox/howto.md index b59227225b..4790c2b24e 100644 --- a/akka-docs/src/main/paradox/howto.md +++ b/akka-docs/src/main/paradox/howto.md @@ -163,4 +163,15 @@ Finally we are able to execute an actor and receive the results or exceptions. @@snip [SupervisedAskSpec.java]($code$/java/jdocs/pattern/SupervisedAskSpec.java) -@@@ \ No newline at end of file +@@@ + +## Scalable Distributed Event Sourcing and CQRS + +The [Lagom Framework](https://www.lagomframework.com) encodes many best practices in combining @ref:[Akka Persistence](persistence.md) and @ref:[Akka Persistence Query](persistence-query.md) +with @ref:[Cluster Sharding](cluster-sharding.md) to build scalable and resilient systems with Event Sourcing and CQRS. + +See @java[[Managing Data Persistence](https://www.lagomframework.com/documentation/current/java/ES_CQRS.html)] +@scala[[Managing Data Persistence](https://www.lagomframework.com/documentation/current/scala/ES_CQRS.html)] and +@java[[Persistent Entity](https://www.lagomframework.com/documentation/current/java/PersistentEntity.html)] +@scala[[Persistent Entity](https://www.lagomframework.com/documentation/current/scala/PersistentEntity.html)] in the Lagom documentation. + diff --git a/akka-docs/src/main/paradox/persistence-query.md b/akka-docs/src/main/paradox/persistence-query.md index d6567ed536..cce3fe6062 100644 --- a/akka-docs/src/main/paradox/persistence-query.md +++ b/akka-docs/src/main/paradox/persistence-query.md @@ -339,6 +339,21 @@ to support "infinite" event streams that include events stored after the initial has completed. It is recommended that the plugin use a configuration property named `refresh-interval` for defining such a refresh interval. + +## Scaling out + +In a use case where the number of events are very high, the work needed for each event is high or where +resilience is important so that if a node crashes the persistent queries are quickly started on a new node and can +resume operations @ref:[Cluster Sharding](cluster-sharding.md) together with event tagging is an excellent fit to +shard events over a cluster. + +The [Lagom framework](https://www.lagom-framework.com), which is built on top of Akka encodes many of the best practices +around this. For more details see @java[[Managing Data Persistence](https://www.lagomframework.com/documentation/current/java/ES_CQRS.html)] +@scala[[Managing Data Persistence](https://www.lagomframework.com/documentation/current/scala/ES_CQRS.html)] and +@java[[Persistent Entity](https://www.lagomframework.com/documentation/current/java/PersistentEntity.html)] +@scala[[Persistent Entity](https://www.lagomframework.com/documentation/current/scala/PersistentEntity.html)] in the Lagom documentation. + + ### Plugin TCK TODO, not available yet. diff --git a/akka-docs/src/main/paradox/persistence.md b/akka-docs/src/main/paradox/persistence.md index 3d8ed629d3..5b545ed8ec 100644 --- a/akka-docs/src/main/paradox/persistence.md +++ b/akka-docs/src/main/paradox/persistence.md @@ -687,6 +687,20 @@ If failure messages are left unhandled by the actor, a default warning log messa No default action is performed on the success messages, however you're free to handle them e.g. in order to delete an in memory representation of the snapshot, or in the case of failure to attempt save the snapshot again. + +## Scaling out + +In a use case where the number of persistent actors needed are higher than what would fit in the memory of one node or +where resilience is important so that if a node crashes the persistent actors are quickly started on a new node and can +resume operations @ref:[Cluster Sharding](cluster-sharding.md) is an excellent fit to spread persistent actors over a +cluster and address them by id. + +The [Lagom framework](https://www.lagom-framework.com), which is built on top of Akka encodes many of the best practices +around this. For more details see @java[[Managing Data Persistence](https://www.lagomframework.com/documentation/current/java/ES_CQRS.html)] +@scala[[Managing Data Persistence](https://www.lagomframework.com/documentation/current/scala/ES_CQRS.html)] and +@java[[Persistent Entity](https://www.lagomframework.com/documentation/current/java/PersistentEntity.html)] +@scala[[Persistent Entity](https://www.lagomframework.com/documentation/current/scala/PersistentEntity.html)] in the Lagom documentation. + ## At-Least-Once Delivery diff --git a/akka-docs/src/main/paradox/remoting-artery.md b/akka-docs/src/main/paradox/remoting-artery.md index 4b71db8054..bec047d34d 100644 --- a/akka-docs/src/main/paradox/remoting-artery.md +++ b/akka-docs/src/main/paradox/remoting-artery.md @@ -1,5 +1,9 @@ # Remoting (codename Artery) + +We recommend @ref:[Akka Cluster](cluster-usage.md) over using remoting directly. As remoting is the +underlying module that allows for Cluster, it is still useful to understand details about it though. + @@@ note This page describes the remoting subsystem, codenamed *Artery* that will eventually replace the diff --git a/akka-docs/src/main/paradox/remoting.md b/akka-docs/src/main/paradox/remoting.md index d0c04414b0..2e92f68ba8 100644 --- a/akka-docs/src/main/paradox/remoting.md +++ b/akka-docs/src/main/paradox/remoting.md @@ -1,11 +1,14 @@ # Remoting +We recommend @ref:[Akka Cluster](cluster-usage.md) over using remoting directly. As remoting is the +underlying module that allows for Cluster, it is still useful to understand details about it though. + For an introduction of remoting capabilities of Akka please see @ref:[Location Transparency](general/remoting.md). @@@ note As explained in that chapter Akka remoting is designed for communication in a -peer-to-peer fashion and it has limitations for client-server setups. In +peer-to-peer fashion and it is not a good fit for client-server setups. In particular Akka Remoting does not work transparently with Network Address Translation, Load Balancers, or in Docker containers. For symmetric communication in these situations network and/or Akka configuration will have to be changed as described in