Akka-management-cluster-bootstrap

akka-management-cluster-bootstrap forms an Akka cluster through service discovery rather than configured seed-node addresses. Nodes expose Akka Management endpoints, discover contact points, and bootstrap the cluster once the required number is confirmed. Discovery can still use fixed local endpoints, but Kubernetes API discovery makes membership lookup deployment-driven. section 13.0 section 13.5

Enable the cluster actor provider, configure contact-point discovery, then start both Akka Management and ClusterBootstrap for the ActorSystem. Set the required contact-point count to the intended initial cluster size; with two initial nodes, bootstrap waits until both are available. Keep business behavior separate: even an empty actor behavior can demonstrate cluster formation. section 13.1.1

import akka.management.scaladsl.AkkaManagement
import akka.management.cluster.bootstrap.ClusterBootstrap
import akka.actor.typed.ActorSystem
import akka.actor.typed.scaladsl.Behaviors
import com.typesafe.config.ConfigFactory
 
object App {
 
  def main(args: Array[String]): Unit = {
    val i = args(0)                         #1
 
    val config = ConfigFactory
      .parseString(s"""                     #2
        akka.remote.artery.canonical.hostname = "127.0.0.$i"
        akka.management.http.hostname = "127.0.0.$i"
        """)
      .withFallback(ConfigFactory.load())   #3
 
    val system =                            #4
      ActorSystem[Nothing](
        Behaviors.empty,
        "testing-bootstrap",
        config)
 
    AkkaManagement(system).start()          #5
    ClusterBootstrap(system).start()        #6
  }
}

This minimal application gives each local node a distinct management and Artery hostname, creates the ActorSystem, then starts management before bootstrap. section 13.1.1

Do not mix configured akka.cluster.seed-nodes with bootstrap configuration: seed nodes take precedence. Before enough contact points are confirmed, logs repeatedly report no seed nodes and too few contacts. Once the threshold is met, the lowest-address node forms the cluster, becomes Up, publishes itself as a seed node through Akka Management, and other nodes join through InitJoin. section 13.1.2

For Kubernetes, discover neighboring pods by label. The lookup name can come, in precedence order, from contact-point-discovery.service-name, AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME, or the ActorSystem name. Supplying the environment variable from a deployment label keeps source code independent of a later deployment-name change. section 13.2.2

apiVersion: apps/v1
kind: Deployment
...
spec:
...
  selector:
    matchLabels:
     app: testing-bootstrap13babc                       #1
...
 
  template:
    metadata:
      labels:
        app: testing-bootstrap13babc                    #1
        actorSystemName: testing-bootstrap13b
    spec:
...
        env:
        - name: AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME     #2
          valueFrom:
            fieldRef:
              apiVersion: v1
              fieldPath: "metadata.labels['app']"

The deployment labels identify cluster pods, while AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME reads the app label for Kubernetes discovery. section 13.2.2

A production deployment pairs bootstrap with operational configuration:

• Use discovery-method = kubernetes-api and a Kubernetes pod-label selector instead of remote Artery addresses or cluster.seed-nodes. section 15.2.3
• Expose Akka Management on port 8558 and configure /alive and /ready as Kubernetes liveness and readiness probes. section 13.2.2
• Give the deployment Kubernetes permissions through a role, service account, and role binding so it can find pods. section 13.5
• Use Split Brain Resolver during network partitions and Akka Singleton when one actor instance must exist cluster-wide. section 13.5