Discovery locates the network destinations that belong to an Akka cluster so Cluster Bootstrap can form or join it without hard-coding a seed node. A local setup can use configuration-based discovery: name the service, list node IP addresses and management ports, expose Akka Management, and start both Akka Management and Cluster Bootstrap. Cluster formation remains separate from business behavior. section 13.1.1
Listing 13.1 Configuration with fixed IPs
akka {
actor.provider = cluster #1
discovery {
config.services = {
testing-bootstrap = { #2
endpoints = [ #3
{
host = "127.0.0.1"
port = 8558
},
{
host = "127.0.0.2"
port = 8558
}
]
}
}
}
management {
cluster.bootstrap {
contact-point-discovery {
service-name = "testing-bootstrap" #4
discovery-method = config #5
}
}
}
This configuration defines a discovery service named testing-bootstrap with two fixed endpoints, then selects the config discovery method for contact-point lookup. section 13.1.1
When bootstrapping a cluster, apply these operational rules:
- Use either configured seed nodes or Cluster Bootstrap; seed-node configuration takes precedence and should not be mixed with bootstrap. section 13.1.2
- Set the required contact-point count to the intended number of initial nodes. A node waits when it cannot confirm enough contact points. section 13.1.1 section 13.1.2
- After enough nodes are found, the lowest-address node forms the cluster and becomes available as a seed node; other nodes discover it and send InitJoin. section 13.1.2
In Kubernetes, discovery can select neighboring pods through labels. The lookup value may come, in precedence order, from the configured service name, the AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME environment variable, or the ActorSystem name. Supplying the value through the deployment environment keeps source code independent of the deployment label. section 13.2.2
Label-based Kubernetes discovery
A three-replica Deployment gives its pods an app label and sets AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME from that label. Akka discovery uses the resulting service name with a Kubernetes API pod-label selector such as app=%s to find cluster nodes. Readiness and liveness probes use the management endpoint. section 13.2.2 section 13.2.2
Listing 13.3 Setting the labels to discover the nodes belonging to the Akka cluster
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 pods for both Kubernetes selection and Akka Cluster Bootstrap service-name lookup. section 13.2.2
