Clustered Mode

Overview

In clustered mode, multiple nodes form a cluster. Actors are location-transparent: you send to a PID, and the framework routes to the correct node. Discovery backends (Consul, etcd, Kubernetes, NATS, mDNS, static) tell the cluster how to find peers.

When to use

High availability and horizontal scaling
Actor distribution across machines
Cluster singletons and relocation

Key components

Discovery — Pluggable provider for peer discovery
Cluster registry — Distributed map (Olric) for actor/grain placement
Remoting — TCP-based message transport between nodes

Configuration

Configure the actor system with WithCluster(clusterConfig) and a discovery provider. Configure remoting with WithRemote(config). The cluster joins membership, and actors can be looked up via ActorOf across nodes. See Service Discovery for provider options.

Registry consistency

Actor and grain creation is synchronous with respect to the cluster registry: Spawn, SpawnOn, SpawnSingleton, and grain activation only return once the registry record is written to the cluster store. As soon as a creation call succeeds, the actor is resolvable by name (for example via ActorOf) and reachable from any node in the cluster, with no propagation window to retry around. When the registry write fails, the creation call returns the error and the actor or grain is stopped, so a failed creation leaves nothing behind.

Relocation

When a node leaves, the leader relocates its actors and grains to remaining nodes. Singleton actors move to the leader; others are distributed. Actors can opt out of relocation via spawn options. See Relocation for the full flow, configuration, and relocatability requirements.

Leadership

Exactly one node in the cluster acts as the coordinator (leader) at any given time. The leader drives internal responsibilities such as relocation and cluster singleton placement, but its status is also queryable from application code:

Method	Purpose
`ActorSystem.IsLeader(ctx)`	Reports whether the local node is the current cluster coordinator.
`ActorSystem.Leader(ctx)`	Returns the `*remote.Peer` describing the current cluster leader.

Both methods require cluster mode; they return ErrClusterDisabled when clustering is not enabled.

isLeader, err := system.IsLeader(ctx)
if err != nil {
    return err
}
if isLeader {
    // this node is the cluster coordinator
}

Whenever the cluster coordinator moves to a different node, every node publishes a LeaderChanged event on its local event stream, alongside NodeJoined and NodeLeft, carrying the new leader’s address. Like the other topology events, it exists for observability (monitoring, logging, dashboards); leadership itself is managed entirely by the framework.

for msg := range subscriber.Iterator() {
    if leaderChanged, ok := msg.Payload().(*actor.LeaderChanged); ok {
        log.Printf("cluster leader is now %s", leaderChanged.Address())
    }
}

LeaderChanged is eventually consistent. It is derived from cluster topology events, so it is published once per leadership change shortly after the cluster settles, and the node’s initial leadership is seeded silently rather than announced. Delivery is best-effort and may be missed under heavy event churn. Treat it as a notification, not a source of truth. When you need the authoritative current leader, call IsLeader(ctx) or Leader(ctx).

Getting Started

Actor

Grains

Remoting

Cluster

Observability

Advanced

Architecture

Contribution

Reference

Meta Framework

Clustered Mode

Overview

When to use

Key components

Configuration

Registry consistency

Relocation

Leadership

​Overview

​When to use

​Key components

​Configuration

​Registry consistency

​Relocation

​Leadership

Overview

When to use

Key components

Configuration

Registry consistency

Relocation

Leadership