or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cluster-management.mdcluster-routing.mdconfiguration-and-management.mdevents-and-state.mdextensibility.mdindex.mdmembers-and-status.md
tile.json

tessl/maven-com-typesafe-akka--akka-cluster

Akka Cluster provides a fault-tolerant decentralized peer-to-peer based cluster membership service with no single point of failure or single point of bottleneck using gossip protocols and automatic failure detection.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.typesafe.akka/akka-cluster_2.11@2.5.x

To install, run

npx @tessl/cli install tessl/maven-com-typesafe-akka--akka-cluster@2.5.0

index.mddocs/

Akka Cluster

Akka Cluster provides a fault-tolerant decentralized peer-to-peer based cluster membership service with no single point of failure or single point of bottleneck. It uses gossip protocols and automatic failure detection to manage cluster membership, enabling applications to build fault-tolerant, decentralized systems with automatic membership management and cluster-aware routing.

Package Information

  • Package Name: akka-cluster
  • Package Type: maven
  • Language: Scala
  • Installation: libraryDependencies += "com.typesafe.akka" %% "akka-cluster" % "2.5.32"
  • Maven Coordinates: com.typesafe.akka:akka-cluster_2.11:2.5.32

Core Imports

import akka.cluster.Cluster
import akka.cluster.ClusterEvent._
import akka.cluster.Member
import akka.cluster.MemberStatus

Basic Usage

import akka.actor.{ActorSystem, Props}
import akka.cluster.{Cluster, ClusterEvent}
import akka.cluster.ClusterEvent._

// Create actor system with cluster configuration
implicit val system = ActorSystem("ClusterSystem")
val cluster = Cluster(system)

// Subscribe to cluster events
val listener = system.actorOf(Props[ClusterListener])
cluster.subscribe(listener, 
  classOf[MemberEvent], 
  classOf[UnreachableMember], 
  classOf[ReachableMember])

// Join cluster
cluster.join(cluster.selfAddress)

// Check cluster state
val currentState = cluster.state
println(s"Members: ${currentState.members}")
println(s"Leader: ${currentState.leader}")

// Leave cluster gracefully
cluster.leave(cluster.selfAddress)

Architecture

Akka Cluster is built around several key components:

  • Cluster Extension: Main entry point (Cluster object and class) providing cluster membership operations
  • Gossip Protocol: Decentralized information dissemination for cluster state synchronization
  • Failure Detection: Automatic detection of unreachable nodes using configurable failure detectors
  • Event System: Comprehensive event model for reacting to cluster state changes
  • Membership Management: Automatic handling of node joining, leaving, and failure scenarios
  • Routing Integration: Cluster-aware routing for distributing work across cluster nodes
  • Multi-Data Center Support: Cross-data center clustering with separate failure detection

Capabilities

Cluster Membership Management

Core cluster operations for joining, leaving, and managing cluster membership. Essential for setting up distributed actor systems.

// Cluster extension access
object Cluster extends ExtensionId[Cluster]
def get(system: ActorSystem): Cluster

// Main cluster operations
class Cluster(system: ExtendedActorSystem) extends Extension {
  def join(address: Address): Unit
  def leave(address: Address): Unit
  def down(address: Address): Unit
  def state: CurrentClusterState
  def selfAddress: Address
  def selfRoles: Set[String]
}

Cluster Management

Event System and State Monitoring

Comprehensive event system for monitoring cluster state changes, member lifecycle events, and reachability updates.

// Event subscription
def subscribe(subscriber: ActorRef, to: Class[_]*): Unit
def unsubscribe(subscriber: ActorRef): Unit

// Core events
sealed trait ClusterDomainEvent
case class MemberUp(member: Member) extends MemberEvent
case class MemberLeft(member: Member) extends MemberEvent
case class UnreachableMember(member: Member) extends ReachabilityEvent
case class LeaderChanged(leader: Option[Address]) extends ClusterDomainEvent

// Current state
class CurrentClusterState(
  members: immutable.SortedSet[Member],
  unreachable: Set[Member],
  seenBy: Set[Address],
  leader: Option[Address]
)

Events and State

Member Information and Status

Member representation, status management, and member lifecycle including addressing and role-based organization.

// Member representation
class Member(
  uniqueAddress: UniqueAddress,
  status: MemberStatus,
  roles: Set[String]
) {
  def address: Address
  def hasRole(role: String): Boolean
  def isOlderThan(other: Member): Boolean
}

// Member status enumeration
sealed abstract class MemberStatus
case object Joining extends MemberStatus
case object Up extends MemberStatus  
case object Leaving extends MemberStatus
case object Down extends MemberStatus

Members and Status

Cluster-Aware Routing

Routing configuration for distributing work across cluster nodes with support for pools and groups, role-based routing.

// Cluster router configurations
case class ClusterRouterPool(
  local: Pool, 
  settings: ClusterRouterPoolSettings
) extends RouterConfig

case class ClusterRouterGroup(
  local: Group,
  settings: ClusterRouterGroupSettings  
) extends RouterConfig

// Router settings
case class ClusterRouterPoolSettings(
  totalInstances: Int,
  maxInstancesPerNode: Int,
  allowLocalRoutees: Boolean,
  useRoles: Set[String]
)

Cluster Routing

Configuration and Settings

Cluster configuration management, settings, and JMX integration for monitoring and management.

// Configuration
class ClusterSettings(config: Config, systemName: String) {
  def SeedNodes: immutable.IndexedSeq[Address]
  def Roles: Set[String] 
  def SelfDataCenter: DataCenter
  def HeartbeatInterval: FiniteDuration
}

// JMX management interface
trait ClusterNodeMBean {
  def join(address: String): Unit
  def leave(address: String): Unit
  def down(address: String): Unit
  def getMemberStatus: String
  def getClusterStatus: String
}

Configuration and Management

Extensibility and SPI

Service Provider Interfaces for extending cluster behavior including custom downing strategies and join validation.

// Downing provider SPI
abstract class DowningProvider {
  def downRemovalMargin: FiniteDuration
  def downingActorProps: Option[Props]
}

// Configuration validation SPI  
abstract class JoinConfigCompatChecker {
  def requiredKeys: immutable.Seq[String]
  def check(toCheck: Config, actualConfig: Config): ConfigValidation
}

Extensibility

Types

// Core addressing
case class UniqueAddress(address: Address, longUid: Long)
type DataCenter = String

// Subscription modes
sealed abstract class SubscriptionInitialStateMode
case object InitialStateAsSnapshot extends SubscriptionInitialStateMode
case object InitialStateAsEvents extends SubscriptionInitialStateMode

// Configuration validation result
sealed trait ConfigValidation
case object Valid extends ConfigValidation
case class Invalid(errorMessages: immutable.Seq[String]) extends ConfigValidation