Service Discovery

In clustered mode, nodes must discover each other. GoAkt uses a pluggable discovery provider that implements the discovery.Provider interface. Pass the provider to ClusterConfig.WithDiscovery() when creating the cluster.

Provider interface

package discovery

type Provider interface {
    ID() string
    Initialize() error
    Register() error
    Deregister() error
    DiscoverPeers() ([]string, error)
    Close() error
}

Method	Purpose
ID	Provider name.
Initialize	One-time setup (e.g., connect to backend).
Register	Register this node with the discovery backend.
Deregister	Remove this node on shutdown.
DiscoverPeers	Return peer addresses as `host:port` strings.
Close	Release resources.

Built-in providers

Provider	Package	Use case
Consul	`discovery/consul`	HashiCorp Consul.
etcd	`discovery/etcd`	etcd.
Kubernetes	`discovery/kubernetes`	K8s API for pod discovery.
NATS	`discovery/nats`	NATS for peer discovery.
mDNS	`discovery/mdns`	Multicast DNS (local networks).
DNS-SD	`discovery/dnssd`	DNS-based service discovery.
Static	`discovery/static`	Fixed list of peer addresses.
Self-managed	`discovery/selfmanaged`	UDP broadcast on LAN; no peer config.

Each provider has its own config type. See the package for constructors and options.

Kubernetes

The Kubernetes provider lists pods through the Kubernetes API, matching the configured labels and status.phase=Running. Pods do not need to be Ready to be discovered: on a cold start no pod is Ready until its actor system has joined the cluster, so readiness cannot gate discovery. Terminating pods and pods without an assigned IP are excluded, and an empty result is treated as a retryable error so that simultaneously starting replicas keep retrying until they see each other.

import "github.com/tochemey/goakt/v4/discovery/kubernetes"

config := &kubernetes.Config{
    Namespace:         "default",
    DiscoveryPortName: "gossip",
    RemotingPortName:  "remoting",
    PeersPortName:     "cluster",
    PodLabels:         map[string]string{"app": "goakt"},
}
provider := kubernetes.NewDiscovery(config)

For production deployments, set WithMinimumPeersQuorum to a majority of the replica count (e.g. 2 for 3 replicas). With the default quorum of 1, a node that cannot reach its peers is allowed to operate as a single-node cluster.

Self-managed (zero config)

The self-managed provider uses UDP broadcast for peer discovery. No third-party services or peer IPs are required; nodes on the same LAN discover each other automatically.

import "github.com/tochemey/goakt/v4/discovery/selfmanaged"

config := selfmanaged.Config{
    ClusterName: "my-app",
    SelfAddress: "192.168.1.10:7946",
}
provider := selfmanaged.NewDiscovery(&config)

Configuration

provider, err := consul.New(config)
// or: etcd.New(config), kubernetes.New(config), etc.
clusterConfig := actor.NewClusterConfig().
    WithDiscovery(provider).
    WithKinds(actor1, actor2)

system, _ := actor.NewActorSystem("app",
    actor.WithRemote(remoteConfig),
    actor.WithCluster(clusterConfig),
)

The provider is used by the cluster to find peers. Remoting must be enabled (WithRemote) for cross-node communication.

Custom provider

Implement discovery.Provider and pass it to WithDiscovery. See Extending GoAkt for the interface and wiring.

Getting Started

Actor

Grains

Remoting

Cluster

Observability

Advanced

Architecture

Contribution

Reference

Meta Framework

Service Discovery

Provider interface

Built-in providers

Kubernetes

Self-managed (zero config)

Configuration

Custom provider

​Provider interface

​Built-in providers

​Kubernetes

​Self-managed (zero config)

​Configuration

​Custom provider

Provider interface

Built-in providers

Kubernetes

Self-managed (zero config)

Configuration

Custom provider