> For the complete documentation index, see [llms.txt](https://tochemey.gitbook.io/goakt/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tochemey.gitbook.io/goakt/features/cluster.md).

# Cluster

## Overview

The cluster engine depends upon the [discovery](https://github.com/Tochemey/goakt/blob/main/discovery/provider.go) mechanism to find other nodes in the cluster. Under the hood, it leverages [Olric](https://github.com/buraksezer/olric) to scale out and guarantee performant, reliable persistence, simple scalability, partitioning (sharding), and re-balancing out-of-the-box. ***It requires remoting to be enabled***. One can implement a custom hasher for the partitioning using the [Hasher](https://github.com/Tochemey/goakt/blob/main/hash/hasher.go) interface and the `Actor System` [option](https://github.com/Tochemey/goakt/blob/main/actors/option.go) to set it. The default hasher uses the `XXH3 algorithm`.

At the moment the following providers are implemented:

* [kubernetes](https://kubernetes.io/docs/home/) [api integration](https://github.com/Tochemey/goakt/blob/main/discovery/kubernetes) is fully [functional](https://github.com/Tochemey/goakt-examples/tree/main/goakt-actors-cluster/k8s)
* [mDNS](https://datatracker.ietf.org/doc/html/rfc6762) and [DNS-SD](https://tools.ietf.org/html/rfc6763)
* [NATS](https://nats.io/) [integration](https://github.com/Tochemey/goakt/blob/main/discovery/nats) is fully functional
* [DNS](https://github.com/Tochemey/goakt/blob/main/discovery/dnssd) is fully [functional](https://github.com/Tochemey/goakt-examples/tree/main/goakt-actors-cluster/dnssd).
* [Static](https://github.com/Tochemey/goakt/blob/main/discovery/static) is fully [functional and for demo purpose](https://github.com/Tochemey/goakt-examples/tree/main/goakt-actors-cluster/static)
* [Consul](https://github.com/Tochemey/goakt/tree/v3.9.0/discovery/consul) discovery provider
* [etcd](https://github.com/Tochemey/goakt/blob/v3.9.0/discovery/etcd/) discovery provider

Note: One can add additional discovery providers using the following [discovery provider](https://github.com/Tochemey/goakt/blob/main/discovery/provider.go).

## Operations Guide

The following outlines the cluster mode operations which can help have a healthy GoAkt cluster:

* One can start a single node cluster or a multiple nodes cluster.
* One can add more nodes to the cluster which will automatically discover the cluster.
* One can remove nodes. However, to avoid losing data, one need to scale down the cluster to the minimum number of nodes which started the cluster.
* *<mark style="color:$info;">**The actor system name should be same across all nodes in the cluster**</mark>*

## Actors Relocation

When a node leaves the cluster, as long as the cluster quorum is stable, its actors are redeployed on the remaining nodes of the cluster. The redeployed actors are created with ***their initial state***. Every field of the Actor set using the `PreStart` will have their value set as expected. On the contrary every field of the Actor will be set to their default go type value because actors are created using reflection.

### Note

One can decide not to recreate/relocate actors when their host node shuts down unexpectedly by using the [`SpawnOption`](https://github.com/Tochemey/goakt/blob/main/actor/spawn_option.go) [**`WithRelocationDisabled()`**](https://github.com/Tochemey/goakt/blob/main/actor/spawn_option.go#L234)&#x20;

One can also disable relocation for a given actor system by using the `Option` [`WithoutRelocation`](https://github.com/Tochemey/goakt/blob/main/actor/option.go#L190) option when creating the actor system. *Child actors are not relocated*.

## Service Discovery

GoAkt ships with a [discovery provider](https://github.com/Tochemey/goakt/blob/main/discovery/provider.go) API that can help any developer to extend GoAkt cluster capability.  See [Service Discovery](/goakt/features/cluster/service-discovery.md)

## Client

The GoAkt client facilitates interaction with a specified GoAkt cluster, contingent upon the activation of cluster mode. See [#client](#client "mention")