Akka Cluster Bootstrap

Akka Cluster Bootstrap supports safely forming a new cluster from discovered nodes or joining a node to an existing cluster. It is an alternative to configuring static seed-nodes.

Akka Cluster Bootstrap does not require any additional system like etcd/zookeeper/consul to be run along side the Akka cluster in order to discover the seed-nodes.


Bootstrap depends on:

A discovery mechanism needs to be chosen. A good default choice is DNS.


Add akka-management-cluster-bootstrap and one or more discovery mechanisms to use for the discovery process.

For example, you might choose to use the DNS discovery and bootstrap extensions:

libraryDependencies ++= Seq(
  "com.lightbend.akka.management" %% "akka-management-cluster-bootstrap" % "0.19.0",
  "com.lightbend.akka.discovery" %% "akka-discovery-dns" % "0.19.0"
dependencies {
  compile group: 'com.lightbend.akka.management', name: 'akka-management-cluster-bootstrap_2.12', version: '0.19.0',
  compile group: 'com.lightbend.akka.discovery', name: 'akka-discovery-dns_2.12', version: '0.19.0'


Akka management must be started as well as the bootstrap process:

// Akka Management hosts the HTTP routes used by bootstrap

// Starting the bootstrap process needs to be done explicitly
Full source at GitHub
// Akka Management hosts the HTTP routes used by bootstrap

// Starting the bootstrap process needs to be done explicitly
Full source at GitHub

Ensure that seed-nodes is not present in configuration and that start() is called on every node.

The following configuration is required, more details for each and additional configuration can be found in reference.conf:

  • akka.management.cluster.bootstrap.contact-point-discovery.service-name set to the name to lookup in service discovery. If unset, it will be derived from the ActorSystem name.
  • akka.management.cluster.bootstrap.contact-point-discovery.discovery-method set to the intended service discovery mechanism. If unset, falls back to the system-wide default from akka.discovery.method.

How it works

  • Service discovery is queried to get initial contact points. At least contact-point-discovery.required-contact-point-nr must be returned to start the bootstrap process.
  • Each node exposes a HTTP endpoint /bootstrap/seed-nodes. This is exposed automatically by starting Akka management.
  • Each node then probes the contact points’s /bootstrap/seed-nodes endpoint to see if a cluster has already been formed
    • If it has it joins the cluster, bootstrap is finished
  • If no cluster exists then each node returns no seed-nodes and the node with the lowest address forms a new cluster and starts advertising itself as a seed node
  • Other nodes will see /bootstrap/seed-nodes of the node that self joined and join its cluster

See full bootstrap process and advanced configuration for more details on the process.

Joining mechanism precedence

As Akka Cluster allows nodes to join to a cluster using a few methods it is the precedence of each method is strictly defined and is as follows:

  • If configured akka.cluster.seed-nodes (in your application.conf) are non-empty, those nodes will be joined, and bootstrap will NOT execute even if start() is called (a warning will be logged though).
  • If an explicit cluster.join or cluster.joinSeedNodes is invokes before the bootstrap completes that joining would take precedence over the bootstrap. This is however not recommended to mix multiple joining methods like this.
  • The Cluster Bootstrap mechanism takes some time to complete, but eventually issues a joinSeednodes.

It is NOT recommended to mix various joining mechanisms. Pick one mechanism and stick to it in order to avoid any surprises during cluster formation. E.g. do NOT set akka.cluster.seed-nodes if you are going to be using the Bootstrap mechanism.

Bootstrap recipes

To see how to use bootstrap in various environments such as Kubernetes see recipes

The source code for this page can be found here.