GithubReference

Service Discovery

GoAkt ships with a discovery provider API that can help any developer to extend GoAkt cluster capability.

By default GoAkt comes bundled with the following fully function discovery providers:

Kubernetes

This provider makes use of the Kubernetes API to discover cluster nodes during cluster mode bootstrap.

Get Started

To enable Kubernetes-based node discovery in your cluster, ensure the following pod labels and ports are correctly defined in your Kubernetes deployment manifest:

Required Pod Labels

  • Namespace: The Kubernetes namespace in which your application is running. This is required for scoping the discovery process.

  • PodLabels: A set of labels that uniquely identify the pods participating in the cluster. These labels are used by the discovery mechanism to filter and locate eligible nodes.

Required Named Ports

Make sure the following named ports are defined in the container spec of your Kubernetes Deployment:

  • DiscoveryPortName: This named port is used by the discovery service to detect and connect to other nodes in the cluster. It enables automatic peer discovery.

  • RemotingPortName: This port facilitates inter-node communication by enabling remote message delivery across cluster nodes.

  • PeersPortName: Used by the distributed cache engine to synchronize actor state across nodes, enabling fault-tolerant replication and consistency.

package main

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

const (
    namespace          = "default"
    applicationName    = "accounts"
    actorSystemName    = "AccountsSystem"
    discoveryPortName  = "discovery-port"
    peersPortName      = "peers-port"
    remotingPortName   = "remoting-port"
)

// define the pod labels to use
// for instance you can use the kubernetes standard labels
labels := map[string]string{
    "app.kubernetes.io/part-of":   "some-part-of",
    "app.kubernetes.io/component": actorSystemName,
    "app.kubernetes.io/name":      applicationName,
}

// define the discovery config
config := kubernetes.Config{
    Namespace:        namespace,
    DiscoveryPortName: discoveryPortName,
    RemotingPortName: remotingPortName,
    PeersPortName:  peersPortName,
    PodLabels:    labels
}

// instantiate the k8 discovery provider
disco := kubernetes.NewDiscovery(&config)

// pass the service discovery when enabling cluster mode in the actor system

Role Based Access

You’ll also have to grant the Service Account that your pods run under access to list pods. The following configuration can be used as a starting point. It creates a Role, pod-reader, which grants access to query pod information. It then binds the default Service Account to the Role by creating a RoleBinding. Adjust as necessary:

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: pod-reader
rules:
  - apiGroups: [""] # "" indicates the core API group
    resources: ["pods"]
    verbs: ["get", "watch", "list"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: read-pods
subjects:
  # Uses the default service account. Consider creating a new one.
  - kind: ServiceAccount
    name: default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Example

A working example can be found here

NATS

This discovery provider make uses of the NATS client to connect to NATS server to discover cluster nodes during cluster mode bootstrap.

Get Started

To use the NATS discovery provider one needs to provide the following:

  • NatsServer: the NATS Server address

  • NatsSubject: the NATS subject to use

  • Timeout: the nodes discovery timeout

  • MaxJoinAttempts: the maximum number of attempts to connect an existing NATs server. Defaults to 5

  • ReconnectWait: the time to backoff after attempting a reconnect to a server that we were already connected to previously. Default to 2 seconds

  • Host: the given node host address

  • DiscoveryPort: the discovery port of the given node

package main

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

const (
    natsServerAddr   = "nats://127.0.0.1:4248"
    natsSubject      = "goakt-gossip"
)

// define the discovery options
config := nats.Config{
    NatsServer:      natsServerAddr,
    NatsSubject:     natsSubject,
    Host:            "127.0.0.1",
    DiscoveryPort:   20380,
}

// instantiate the NATS discovery provider by passing the config and the hostNode
disco := nats.NewDiscovery(&config)

// pass the service discovery when enabling cluster mode in the actor system

DNS

This provider performs nodes discovery based upon the domain name provided. This is very useful when doing local development using docker.

Get Started

To use the DNS discovery provider one needs to provide the following:

  • DomainName: the domain name

  • IPv6: it states whether to lookup for IPv6 addresses.

package main

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

const domainName = "accounts"

// define the discovery options
config := dnssd.Config{
    dnssd.DomainName: domainName,
    dnssd.IPv6:       false,
}
// instantiate the dnssd discovery provider
disco := dnssd.NewDiscovery(&config)

// pass the service discovery when enabling cluster mode in the actor system

Example

A working example can be found here

Static

This provider performs nodes discovery based upon the list of static hosts addresses. The address of each host is the form of host:port where port is the gossip protocol port.

Get Started

package main

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

// define the discovery configuration
config := static.Config{
    Hosts: []string{
    "node1:3322",
    "node2:3322",
    "node3:3322",
    },
}
// instantiate the dnssd discovery provider
disco := static.NewDiscovery(&config)

// pass the service discovery when enabling cluster mode in the actor system

Example

A working example can be found here

PreviousClusterNextCluster Singleton

Last updated