Glossary of Terms


A command comes from a sender, and a reply may be sent to the sender. A command expresses the intention to alter the state of an Entity. A command is materialized by a message received by a Service implementation. Commands may come from outside the Stateful service, perhaps from other stateful services, other non-Cloudstate services, or the outside world, or they may come from within the service, invoked as a side effect or to forward command handling from another command. Commands are not persisted. A command might fail.

Command handler

A command handler is the code that handles a command. It may validate the command using the current state, and may emit events as part of its processing. A command handler must not update the state of the entity directly, only indirectly by emitting events. If a command handler does update the state, then when the entity is passivated (removed from memory), those updates will be lost.


You implement one or more entities that are bundled into a Service implementation. An entity is conceptually equivalent to a class, or a type of state. An entity will have multiple Entity instances, each of which has a unique ID and can handle commands. For example, a service may implement a chat room entity, encompassing the logic associated with chat rooms, and a particular chat room may be an instance of that entity, containing a list of the users currently in the room and a history of the messages sent to it. Each entity has a particular Entity type, or State model, which define how the entity’s state is persisted, shared, and what its capabilities are.

Entity instance

An instance of an Entity. Each entity instances is identified by a unique Entity key. An entity holds state in the Service implementation, and depending on the Entity type this state is held within the context of a gRPC stream.

Entity key

A key used to identify instances of an Entity. All Commands must contain the entity key so that the command can be routed to the right instance of the entity that the command is for. The gRPC descriptor for the Entity Service annotates the incoming message types for the entity to indicate which field(s) contain the entity key.

Entity Service

An entity service is a gRPC service that allows interacting with an Entity. Akka Serverless makes this service available for other Kubernetes services and ingresses to consume, while the Service implementation provides the implementation of the entity business logic. Note that the service is not implemented directly, by the service implementation like a normal gRPC service. Rather, it is implemented by Cloudstate, which enriches the incoming and outgoing gRPC messages with state management capabilities, such as the ability to receive and update state.

Entity type

The type of state management that an Entity uses. Available types include Event Sourced entity and Replicated Entity. Each type has its own sub protocol that it uses for state management, to convey state and updates specific to that type.


An event is a piece of data that gets persisted and indicates that a change has occurred to an entity. Events are stored in a journal, and are read and replayed each time the entity is reloaded by Cloudstate’s state management system. Events have already happened. The event is how the current service finds out about it—​we can’t change the event. An event emitted by one service might be interpreted as a command by another.

Event handler

An event handler is the only piece of code that is allowed to update the state of the entity. It receives events, and, according to the event, updates the state.

Event Sourced entity

A type of Entity that stores its state using a journal of events, and restores its state by replaying that journal. These are discussed in more detail in Event sourcing.


A programming-language neutral way to describe the contract of your service in terms of Protocol Buffers (or Protobuf for short). As a developer, you write one file (.proto) that specifies the contract of your service containing the input, output, and operations. External consumers will use the contract to know how to call your service.

Replicated Entity

A type of Entity that stores its state using a Conflict-free Replicated Data Type (CRDT), which is replicated across different nodes of the service. These are discussed in more detail in Replicated Entities.

Service implementation

A service implementation includes the entity implementations that you write, package as a Docker image, and deploy as a Stateful service.


A snapshot records current state of an entity. Cloudstate persists snapshots periodically as an optimization. With snapshots, when the entity is reloaded from the journal, the entire journal doesn’t need to be replayed, just the changes since the last snapshot.


The state is simply data—​the current set of values for an entity instance. Event Sourced entities hold their state in memory.

State model

Each entity uses one of the Cloudstate-supported state models. Currently, these include Replicated Entity and Event Sourced entity.

Stateful service

A stateful service is a deployable unit. It is represented in Kubernetes as a StatefulService resource. It contains a Service implementation, and may reference a Stateful store. The Cloudstate operator transforms a stateful service into a Kubernetes Deployment resource. The Cloudstate operator then defines a Kubernetes Service to expose the stateful service to the outside world.

Stateful store

A stateful store is an abstraction over a datastore, typically a database. It is represented in Kubernetes as a StatefulStore resource. Akka Serverless manages the stateful store for you.