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 api integration is fully functional

• mDNS and DNS-SD

• NATS integration is fully functional

• DNS is fully functional

• Static is fully functional and for demo purpose

Kubernetes

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

Get Started

To get the kubernetes discovery working as expected, the following pod labels need to be set:

• app.kubernetes.io/part-of: set this label with the actor system name

• app.kubernetes.io/component: set this label with the application name

• app.kubernetes.io/name: set this label with the application name

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 discovery config
config := kubernetes.Config{
    ApplicationName:  applicationName,
    ActorSystemName:  actorSystemName,
    Namespace:        namespace,
    DiscoveryPortName: discoveryPortName,
    RemotingPortName: remotingPortName,
    PeersPortName:  peersPortName,
}

// 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

• ActorSystemName: the actor system name

• ApplicationName: the application name

• 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"
    applicationName  = "accounts"
    actorSystemName  = "AccountsSystem"
)

// define the discovery options
config := nats.Config{
    ApplicationName: applicationName,
    ActorSystemName: actorSystemName,
    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