ClusterHelper

This library is built on top of :syn library, help to manage dynamic Elixir cluster on environment like Kubernetes. Each node has roles like :data, :web, :cache other nodes join to cluster can easy get nodes follow a role in cluster. Can use scope for seperating to sub cluster (current version doesn't support overlapped sub cluster).

Library can use with easy_rpc for easy to develop an Elixir cluster.

Installation

If available in Hex, the package can be installed by adding cluster_helper to your list of dependencies in mix.exs:

def deps do
  [
    {:cluster_helper, "~> 0.2"}
  ]
end

Add :cluster_helper to extra_application in mix.exs for ClusterHelper can start with your app.

  def application do
    [
      mod: {MyApp.Application, []},
      extra_applications: [:cluster_helper]
    ]
  end

Usage

Note: You need join node to cluster by other library (like libcluster) or manually.

Add rols to config for node

config :cluster_helper,
  # optional, all roles of current node. Can add role in runtime.
  roles: [:data, :web],
  # optional, for scope of :syn lib. default scope is ClusterHelper
  scope: :my_cluster ,
  # optional, default 5_000, timeout for sync between nodes.
  pull_timeout: 5_000, # ms
  # optional, default 7_000, time interval for pull from other nodes
  pull_interval: 10_000 # ms

If node join/leave cluster other nodes will auto update in pull event.

If add role for node other nodes will received a event for update new role of that node.

Query nodes by role in cluster

ClusterHelper.get_nodes(:data)

# [:node1, :node2]

check role of a node in cluster

ClusterHelper.get_roles(:node1)

# [:data, :web]

Support for adding callback to trigger new role or node.

# config/config.exs
config :cluster_helper, event_handler: MyApp.ClusterEvents

# lib/my_app/cluster_events.ex
defmodule MyApp.ClusterEvents do
  @behaviour ClusterHelper.EventHandler

  @impl true
  def on_role_added(node, role) do
    Logger.info("#{node} gained role #{inspect(role)}")
  end

  @impl true
  def on_node_added(node) do
    Phoenix.PubSub.broadcast(MyApp.PubSub, "cluster", {:node_up, node})
  end
end

Test local cluster without integrated with other app

Start 2 nodes

Start node1:

iex --name node1@127.0.0.1 --cookie need_to_change_this -S mix

iex --name node2@127.0.0.1 --cookie need_to_change_this -S mix

Join & Verify all nodes by run cmd in node2 shell:

Node.connect(:"node1@127.0.0.1")

Node.list()

In each iex shell add rule by cmd:

ClusterHelper.add_roles([:role1, :role2])

Verify data synced by cmd:

ClusterHelper.get_nodes(:role1)

Example

You can get a full example using with EasyRpc lib on Github

Support AI agents & MCP for dev

Run this command for update guide & rules from deps to repo for supporting ai agents.

mix usage_rules.sync AGENTS.md --all \
  --link-to-folder deps \
  --inline usage_rules:all

Run this command for enable MCP server

mix tidewave

Config MCP for agent http://localhost:4112/tidewave/mcp, changes port in mix.exs file if needed. Go to Tidewave for more informations.