akka / akka-guide

Examples how to implement Microservices using Akka

Akka

We believe that writing correct concurrent & distributed, resilient and elastic applications is too hard. Most of the time it's because we are using the wrong tools and the wrong level of abstraction.

Akka is here to change that.

Using the Actor Model we raise the abstraction level and provide a better platform to build correct concurrent and scalable applications. This model is a perfect match for the principles laid out in the Reactive Manifesto.

For resilience, we adopt the "Let it crash" model which the telecom industry has used with great success to build applications that self-heal and systems that never stop.

Actors also provide the abstraction for transparent distribution and the basis for truly scalable and fault-tolerant applications.

Learn more at akka.io.

Reference Documentation

The reference documentation is available at doc.akka.io, for Scala and Java.

Current versions of all Akka libraries

The current versions of all Akka libraries are listed on the Akka Dependencies page. Releases of the Akka core libraries in this repository are listed on the GitHub releases page.

Community

You can join these groups and chats to discuss and ask Akka related questions:

• Forums: discuss.akka.io
• Issue tracker:

In addition to that, you may enjoy following:

• The news section of the page, which is updated whenever a new version is released
• The Akka Team Blog
• The Akka articles in the Lightbend Blog
• @akkateam on Twitter
• Questions tagged #akka on StackOverflow

Contributing

Contributions are very welcome!

If you see an issue that you'd like to see fixed, or want to shape out some ideas, the best way to make it happen is to help out by submitting a pull request implementing it. We welcome contributions from all, even you are not yet familiar with this project, We are happy to get you started, and will guide you through the process once you've submitted your PR.

Refer to the CONTRIBUTING.md file for more details about the workflow, and general hints on how to prepare your pull request. You can also ask for clarifications or guidance in GitHub issues directly, or in the akka/dev chat if a more real time communication would be of benefit.

License

Akka is licensed under the Business Source License 1.1, see LICENSE.

akka-guide's Issues

gRPC ShoppingCartService

and remote the HTTP routes

how to: write an integration test

The tutorial will probably only cover some unit tests. Integration testing with real Cassandra and Kafka can be a separate "how to recipe"

Document the gRPC service

port assignments

When running locally it's necessary to use different ports, but in cloud env it would probably use a fixed port. Ports for Akka Remoting, gRPC server and Akka Management.

We need to adjust Main to take local or cloud environment into account. Probably easiest to let Main amend the port configurations only if the port is defined as argument to main. Otherwise use the conf as is.

Make site deploy on merge to main

Enable deploy of the Antora generated site to akka.io/akka-microservies.

failed: IntegrationSpec Kafka

The IntegrationSpec is failing for me now. Strange, since I tried it when the docker-compose PR was added. I have tried to restart with docker-compose down.

[2020-08-21 11:36:55,305] [ERROR] [akka.actor.OneForOneStrategy] [] [IntegrationSpec-akka.actor.default-dispatcher-5] - Failed to construct kafka consumer
akka.actor.ActorInitializationException: akka://IntegrationSpec/system/kafka-consumer-1: exception during creation
	at akka.actor.ActorInitializationException$.apply(Actor.scala:196)
	at akka.actor.ActorCell.create(ActorCell.scala:661)
	at akka.actor.ActorCell.invokeAll$1(ActorCell.scala:513)
	at akka.actor.ActorCell.systemInvoke(ActorCell.scala:535)
  | => sat akka.dispatch.Mailbox.processAllSystemMessages(Mailbox.scala:295)
	at akka.dispatch.Mailbox.run(Mailbox.scala:230)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
	at java.base/java.lang.Thread.run(Thread.java:834)
Caused by: org.apache.kafka.common.KafkaException: Failed to construct kafka consumer
	at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:820)
	at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:631)
	at akka.kafka.ConsumerSettings$.createKafkaConsumer(ConsumerSettings.scala:237)
	at akka.kafka.ConsumerSettings$.$anonfun$apply$3(ConsumerSettings.scala:111)
	at akka.kafka.internal.KafkaConsumerActor.akka$kafka$internal$KafkaConsumerActor$$applySettings(KafkaConsumerActor.scala:459)
	at akka.kafka.internal.KafkaConsumerActor.preStart(KafkaConsumerActor.scala:436)
	at akka.actor.Actor.aroundPreStart(Actor.scala:548)
	at akka.actor.Actor.aroundPreStart$(Actor.scala:548)
	at akka.kafka.internal.KafkaConsumerActor.aroundPreStart(KafkaConsumerActor.scala:212)
	at akka.actor.ActorCell.create(ActorCell.scala:641)
	... 7 common frames omitted
Caused by: org.apache.kafka.common.config.ConfigException: No resolvable bootstrap urls given in bootstrap.servers
	at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:88)
	at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:47)
	at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:735)
	... 16 common frames omitted

Start Cassandra for running the services

Add a docker-compose configuration for Cassandra to run the example easily in a local setting.

auto-start-journals config

Maybe good to include in default config:

akka.persistence.journal.auto-start-journals = ["akka.persistence.cassandra.journal"]

Review/unify look of images

Images in some of the Concepts pages e.g. https://github.com/akka/akka-platform-guide/blob/main/docs-source/docs/modules/concepts/assets/images/concepts/internal-and-external-communication.png) were directly copy/pasted from the original location.

As a consequence, the look of images in https://github.com/akka/akka-platform-guide/tree/main/docs-source/docs/modules/concepts/assets/images varyies or doesn't fully match the text (as it evolved).

Add the Popularity projection

See #11

setup PR validation

Travis and CLA checker

Add canonical URL

In #85 we added content copy/pasted from https://developer.lightbend.com/docs/introduction/traditional-architecture.html. The page https://github.com/akka/akka-platform-guide/blame/main/docs-source/docs/modules/concepts/pages/concepts-traditional-architecture.adoc should include a canonical tag pointing to the page in https://developer.lightbend.com....

Tutorial navigation

I don't know if we will get navigation for free with the real style. Otherwise we need to add links to next step at the the end of the tutorial pages.

gRPC service discovery

between SendOrderProjection and ShoppingOrderService

see #31

Document PublishEventProjection

See #21

rename packages

For no reason the packages became sample.shoppingcart, sample.shoppinganalytics and sample.shoppingorder. Would be better with sample.shopping.cart, sample.shopping.analytics and sample.shopping.order

IntelliJ live templates

I played with the idea that we could share some live templates for typical scaffolding.

Created a few in attached akka-templates.zip to illustrate.

That zip can be imported from File > Manage IDE Settings > Import Settings

It adds a Akka Microservices scaladsl template group. The templates are prefixed with akka- so you can try by creating a Cart.scala file and then akka + ctrl-space and select akka-Entity

how to: reduce build dependencies

Describe what dependencies that can be removed (from the empty template project) when different things are not used.

how to: enable TLS for gRPC

Split application.conf in separate files

For example cluster and persistence config in separate files. Imported by application.conf

[EPIC] Concepts around reactive microservices

Some material from https://www.lagomframework.com/documentation/1.6.x/scala/CoreConcepts.html would be good to include here.

Fail the docs generation (in author-mode) on Warnings

AsciiDoc supports lowering the failure of the processor using --failure-level=LEVEL (defaults to FATAL).

It'd be useful to setup --failure-level=WARNING. I've been looking around but can't locate how to setup our Makefile/antora build to pass that setting down into the asciidoctor command. Edit: that setting is for asciidoctorCLI, not asciidcotor.js.

failed: IntegrationSpec

In Travis, see attached log
IntegrationSpec.log

Use of bootstrap and discovery

Bootstrap - should we use it locally too so we don't end up having to describe seed nodes and bootstrap. Also avoids not having bootstrap.start being conditional for local.

Discovery - consider not using it for Kafka/gRPC/Cassandra. In k8s these can be headless services and for local we can override them to be localhost with config.

Review shutdown of the Kafka consumer flow in `ShoppingCartEventConsumer`

Don't create keyspace and tables automatically

The Main of the sample is now creating keyspace and tables automatically, which is not our recommendation for production. Ok to do that from tests.

How should we deal with this for running locally? Easy of running vs the right thing for production?

how to: scale write-side and read-side independent of each other

I don't think "write-model" and "read-model" are great names for the roles.

"write-side" and "read-side" are slightly better. A projection reads the events. Entities writes the events.

"entity" and "projection" might be better?

Also, define constants in the code for these roles.

Use PersistenceTestKit in ShoppingCartSpec

Style of writing

A question for Ruth.

In the tutorial I wanted to encourage the reader to actively build up the application by adding code themselves, even if that only means copy paste from the documentation snippets.

I used instructions like like "Add class ...", "You need to define...", "You implement the...", "Let's add...". followed by code snippet.

I don't know if that is a good style to use, or if it should be more indirect and describing like "This implements the..." followed by code snippet.

State target audience

Refs #65

The Overview page should include a section stating what's the target audience.

Later, we could have specific audiences for each section:

• one audience for the tutorial
• one audience for a (basic) HOWTO
• another audience for an advanced HOWTO

Tutorial source code download

Even though the tutorial will be thorough and include all source code I think we should provide a download of the full source code for each part. I'm thinking that a zip file with different directories for each part would be nice.

grpc network interface conf

The config of the grpc interface is still defined as 127.0.0.1. We need different config for application.conf and local.conf

Two places:

shopping-cart.grpc.interface
shopping-order.grpc.interface

Add PublishEventsProjection and AnalyticsService (Kafka)

See #11

Replace the old ShoppingCartProjectionHandler and EventProcessor

Document SendOrderProjection

See #15

Travis cache

Do we need to add some caching instructions for Travis to avoid downloading the docker stuff each time?

Document ItemPopularityProjection

See #14

Enable Akka design on the site

I've initiated work to get an Akka design for Antora.

Rename repository to akka-platform-guide

or akka-microservices-guide

[epic] Example project

The purpose of this ticket is to describe an overview of the full example and its pieces. It will be broken down in more concrete tasks.

The example should illustrate the following technical pieces:

• gRPC server
• gRPC client call to another service
• EventSourcedBehavior with Sharding
• Projection that is publishing events to Kafka
• Projection that is updating a query database model

The full example could look like this:

Shopping Cart Service

• CartService provides a gRPC server interface.
• CartEntity represents the individual shopping carts (EventSourcedBehavior with Sharding).
• CartService sends commands to CartEntity with ask via Sharding EntityRef.
• CartEntity stores events in Cassandra journal. (Internal representation in CBOR format.)
• PublishEventsProjection sends all shopping cart events to a Kafka topic. (External representation in protobuf format.)
• PopularityProjection updates a count per item of how many shopping carts that include the item. Representing how popular the item is. The projection is stored in a Cassandra query db, which can be queried from the CartService.
• SendOrderProjection calls the OrderService over gRPC for CheckedOut events. The order should contain the items and quantities of the cart and that can be obtained with an ask to the CartEntity.

Order Service

• OrderService provides a gRPC server interface that is called from the SendOrderProjection. (The example doesn’t have to do anything more than logging here.)

Analytics Service

• AnalyticsService consumes shopping cart events from the Kafka topic with the purpose of producing statistics/reports of customer behavior. (Alpakka Kafka to consume the events.) (The example doesn’t have to do anything more than logging here.)

The example should be introduced step-by-step, with deployment of each step:

• CartService with one gRPC service method and dummy implementation (logging). Use grpcurl to interact with the service.
• Add CartEntity and interaction from CartService.
• Add PublishEventsProjection and AnalyticsService.
• Add SendOrderProjection and OrderService.
• Add PopularityProjection and popularity query from CartService.

(Should the projections be introduced in a different order?)
(Should it start with a single instance and introduce Akka cluster on the way?)

add readiness, liveness checks to the services

using Akka Management health checks

remove val project in build.sbt

We can use a flat build, since it's not multi-project builds.

Also, the full list of dependencies can be included in all projects even though not used in all.

I'm thinking that we will have an empty project template with the dependencies and plugins. Then we could have a "how to reduce build dependencies" describing what can be removed if not used.

Use Alpakka Kafka testkit to spin up Kafka for integration tests

[EPIC] Port the Shopping sample to Java

Should it demo Maven or Gradle or sbt or 2/3 or all?

• port the shopping cart service #213
• port the orders service
• port the analytics service

how to: evolve proto schemas

The documentation should explain the basics of how APIs can be evolved when using Protobuf.

Renaming

With what we've learned about structuring this guide with Antora we should consider renaming things:

The repository: akka-microservices-samples -> akka-platform-guide
The example: cqrs -> shopping-microservices

The tutorial directory can be removed so that shopping-microservices just contains the tutorial.

References #42

Documentation structure

I would like to suggest that we structure the documentation like Django documentation:
https://docs.djangoproject.com/en/3.1/internals/contributing/writing-documentation/#how-the-documentation-is-organized

• Tutorial - step by step tutorial building up the sample project
• Concepts - general explanation of concepts and motivations
• How to - recipes for specific things (additions to the tutorial sample)
• Reference - overview of links to reference documentation

I know there is an article describing how to structure documentation around these 4 topics, but I can't find it at the moment.

Create the Order Service (gRPC)

See #11

Update to Akka Projection 1.0

Add the SendOrder projection and Order Service (gRPC)

See #11

Create g8 template for empty project

It will be the starting point for the tutorial and contains:

• build with dependencies and gRPC plugin
• configuration
• empty Main class

Until we have this in place the docs-source/docs/modules/shopping-microservices/examples/empty-shopping-cart-service-scala in branch wip-empty-project-patriknw can be used. https://github.com/akka/akka-platform-guide/tree/wip-empty-project-patriknw/docs-source/docs/modules/shopping-microservices/examples/empty-shopping-cart-service-scala