# 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](https://tochemey.gitbook.io/goakt/features/cluster/service-discovery "mention")

## Client

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tochemey.gitbook.io/goakt/features/cluster.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.