Service Discovery

​

Provider interface

package discovery

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

• 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. Called when the node boots. See Discovery happens at boot for what an empty list and an error mean.
• Close: Release resources.

​

Built-in providers

• Static: Package discovery/static. A fixed list of peer addresses. Use when the topology is known upfront.
• Kubernetes: Package discovery/kubernetes. Lists pods through the Kubernetes API. Use inside a Kubernetes cluster.
• NATS: Package discovery/nats. Nodes answer discovery requests over a NATS subject. Use when NATS is already part of the platform.
• mDNS: Package discovery/mdns. Multicast DNS on the local network. Use for development on one LAN.
• DNS-SD: Package discovery/dnssd. Resolves a DNS name to the peers’ addresses. Use when DNS already knows the nodes.
• Consul: Package discovery/consul. Registers the node as a Consul service with a health check.
• etcd: Package discovery/etcd. Registers the node under a leased key.
• Self-managed: Package discovery/selfmanaged. UDP broadcast on the LAN with no backend and no peer list. Use for local clusters and tests.

​

Static

• Hosts: Required. The peer addresses. Each entry is validated as a TCP address.

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

config := &static.Config{
    Hosts: []string{
        "10.0.0.1:4042",
        "10.0.0.2:4042",
        "10.0.0.3:4042",
    },
}
provider := static.NewDiscovery(config)

​

Kubernetes

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: goakt-discovery
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["list"]

• Namespace: Required. The namespace to list pods in.
• PodLabels: Required. A pod must carry all of these labels to count as a peer.
• DiscoveryPortName: Required. The name of the container port carrying membership gossip. Peer addresses are built from the pod IP and this port.
• RemotingPortName and PeersPortName: Deprecated and ignored. Peers learn each other’s remoting and peers ports from the node metadata exchanged once they are members. Existing configurations that set them keep working.

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

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

​

NATS

• NatsServer: Required. The server address, in the form nats://host:port.
• NatsSubject: Required. The subject the cluster uses for discovery traffic.
• Host and DiscoveryPort: Required. The address this node advertises.
• Timeout: How long DiscoverPeers waits for answers. Default 1s.
• MaxJoinAttempts: How many times to try connecting to the NATS server before giving up. Default 5.
• ReconnectWait: The backoff between connection attempts. Default 2s.

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

config := &nats.Config{
    NatsServer:    "nats://127.0.0.1:4222",
    NatsSubject:   "goakt-discovery",
    Host:          "10.0.0.1",
    DiscoveryPort: 4042,
}
provider := nats.NewDiscovery(config)

​

mDNS

• ServiceName: Required. The cluster name. All nodes of one cluster share it, and each node adds its own suffix on the wire.
• Service: Required. The service type, for example _goakt._tcp.
• Domain: Required. The mDNS domain. local and local. are both accepted.
• Port: The discovery port this node announces. Peers announcing a different port are ignored.
• IPv6: Optional. When true, IPv6 addresses are returned alongside IPv4 ones.

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

config := &mdns.Config{
    ServiceName: "my-app",
    Service:     "_goakt._tcp",
    Domain:      "local.",
    Port:        4042,
}
provider := mdns.NewDiscovery(config)

​

DNS-SD

• DomainName: Required. The name to resolve.
• IPv6: Optional. When true, only AAAA records are returned. Otherwise all records are returned.

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

config := &dnssd.Config{
    DomainName: "my-app.default.svc.cluster.local",
}
provider := dnssd.NewDiscovery(config)

​

Consul

• Address: Required. The Consul agent, for example 127.0.0.1:8500.
• ActorSystemName: Required. Used as the service name and tag, so nodes of different systems do not discover each other.
• Host and DiscoveryPort: Required. The address registered for this node.
• Datacenter: Optional. The datacenter to register in and query. Defaults to the agent’s datacenter.
• Token: Optional. The ACL token for authenticated requests.
• Timeout: The limit for each Consul request. Default 10s.
• Context: Optional. The context Consul requests run under. Defaults to a background context.
• HealthCheck: The TCP check Consul runs against the node. Interval defaults to 10s and Timeout to 3s.
• QueryOptions: How peers are looked up. OnlyPassing restricts results to healthy services. AllowStale accepts answers from follower agents. WaitTime bounds blocking queries. Near sorts results by distance to a node. Datacenter overrides the datacenter for queries. When the field is nil, WaitTime defaults to 1s and the two flags to false.

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

config := &consul.Config{
    Address:         "127.0.0.1:8500",
    ActorSystemName: "my-app",
    Host:            "10.0.0.1",
    DiscoveryPort:   4042,
}
provider := consul.NewDiscovery(config)

​

etcd

• Endpoints: Required. The etcd endpoints.
• ActorSystemName: Required. The key prefix, so nodes of different systems do not discover each other.
• Host and DiscoveryPort: Required. The address registered for this node.
• TTL: Required. The lease duration in seconds. It bounds how long a dead node stays visible.
• DialTimeout: Required. The limit for connecting to etcd.
• Timeout: Required. The limit for each etcd request.
• Context: Optional. Must outlive the provider: cancelling it stops the keep-alive and removes the node from etcd. Defaults to a background context.
• TLS, Username, Password: Optional. Client TLS and authentication.

import (
    "time"

    "github.com/tochemey/goakt/v4/discovery/etcd"
)

config := &etcd.Config{
    Endpoints:       []string{"127.0.0.1:2379"},
    ActorSystemName: "my-app",
    Host:            "10.0.0.1",
    DiscoveryPort:   4042,
    TTL:             10,
    DialTimeout:     5 * time.Second,
    Timeout:         5 * time.Second,
}
provider := etcd.NewDiscovery(config)

​

Self-managed (zero config)

• ClusterName: Required. Only nodes with the same name discover each other.
• SelfAddress: Required. The host:port this node advertises, on the discovery port.
• BroadcastPort: The UDP port for announcements. Default 7947.
• BroadcastInterval: How often this node announces itself. Default 5s.
• BroadcastAddress: The target for announcements. Default 255.255.255.255. Set it to 127.0.0.1 to keep discovery on the loopback interface, for example in tests.

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 := consul.NewDiscovery(config)
// or: etcd.NewDiscovery(config), kubernetes.NewDiscovery(config), etc.
clusterConfig := actor.NewClusterConfig().
    WithDiscovery(provider).
    WithDiscoveryPort(4042).
    WithPeersPort(4043).
    WithKinds(actor1, actor2)

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

​

Discovery happens at boot

• Quorum of 1 (the default): the node serves as soon as it has booted and does not query the provider again. A node that booted alone stays alone until another node joins it.
• Quorum of 2 or more: the node serves nothing until the cluster has that many members, and while it is below the quorum it queries the provider again every five seconds. A node that found nobody at boot keeps looking.

​

The two rules a provider must follow

1. A node is visible before it reads. Once Register has returned on a node, DiscoverPeers on the other nodes lists it.
2. Reads are consistent. DiscoverPeers returns every node whose Register returned before the call.

​

When the view may be incomplete, return an error

package app

import (
    "errors"

    "github.com/tochemey/goakt/v4/discovery"
)

// errNoPeerListed makes the cluster retry the join.
var errNoPeerListed = errors.New("no peer is listed yet")

// requirePeers wraps a discovery provider and fails the query while the
// provider lists no node other than this one.
type requirePeers struct {
    discovery.Provider
    // self is this node's discovery address, host:port, as the provider lists it.
    self string
}

// DiscoverPeers returns the wrapped provider's peers, or errNoPeerListed
// when none of them is another node.
func (x *requirePeers) DiscoverPeers() ([]string, error) {
    peers, err := x.Provider.DiscoverPeers()
    if err != nil {
        return nil, err
    }

    for _, peer := range peers {
        if peer != x.self {
            return peers, nil
        }
    }

    return nil, errNoPeerListed
}

clusterConfig := actor.NewClusterConfig().
    WithDiscovery(&requirePeers{Provider: provider, self: "10.0.0.1:3322"})

​

Custom provider