Process overview

Specify service interface and domain model

The main components of a Kalix service are:

  • Stateful Entities

  • Stateless Actions

  • Views, which return the state of multiple instances of a stateful entity.

We recommend that you separate the service API and Entity domain data model. Separating the service interface and data model in different classes allows you to evolve them independently.

Kickstart a project using the Getting started guide.

Implement components

Stateful services can implement Value Entity or Event Sourced Entity and View components. Stateless services implement Actions. Typically, a stateful service should only have one Entity type, but can also include Actions and Views.

Actions

Actions are stateless functions that can be triggered by HTTP calls. They can also subscribe to published events, and they can send commands to other services based on the events they receive. For more information about writing actions see Implementing Actions.

Entities

Stateful services encapsulate business logic in Value Entities or Event Sourced Entities. At runtime, command messages invoke operations on Entities. A command may only act on one Entity at a time.

To learn more about Kalix entities see Implementing Value Entities and Implementing Event Sourced Entities.

If you would like to update multiple Entities from a single command, you can use forwarding and side effects.

For more information see Actions as Controllers and Running Side Effects.

Services can interact asynchronously with other services and with external systems. Event Sourced Entities emit events to a journal, to which other services can subscribe. By configuring your own publish/subscribe (pub/sub) mechanism, any service can publish their own events and subscribe to events published by other services or external systems.

Views

A View provides a way to retrieve state from multiple Entities based on a query. You can query non-key data items. You can create views from Value Entity state, Event Sourced Entity events, and by subscribing to topics. For more information about writing actions see Implementing Views.

Testing your application

It is good practice to write unit tests and integration tests as you implement your services.

Kalix Spring SDK provides a test kit dependency that you can use to write unit tests for Actions and Entities as well as integration tests. Please consult the component specific pages to learn more about writing unit tests and integration tests for your application.

Package service

Use Docker to package your service and any of its dependencies. See the following pages for more information:

Run locally

You can test and debug your services by running them locally before deploying to Kalix.

Deploy to Kalix

After testing locally, deploy your service to Kalix using the CLI or the Console. The following pages provide information about deployment: