Search documentation of macula

# macula_cluster_gossip (macula v0.44.2)

View Source

Macula UDP Multicast Gossip Cluster Strategy.

Zero-config cluster formation using UDP multicast for LAN discovery. Equivalent to libcluster's Cluster.Strategy.Gossip.

### How It Works

Each node: 1. Joins a multicast group (default 230.1.1.251) 2. Periodically broadcasts its node name 3. Listens for broadcasts from other nodes 4. Connects to discovered nodes via Erlang distribution

### Configuration

Start with options:

       {ok, _Pid} = macula_cluster_gossip:start_link(#{
           multicast_addr => {230, 1, 1, 251},  %% Multicast group
           port => 45892,                        %% UDP port
           broadcast_interval => 1500,           %% ms between broadcasts
           multicast_ttl => 1,                   %% TTL (1 = same subnet)
           secret => <<"my-cluster-secret">>     %% Optional: filter by secret
       }).

Or from environment variables:

       %% MACULA_GOSSIP_ADDR=230.1.1.251
       %% MACULA_GOSSIP_PORT=45892
       %% MACULA_GOSSIP_SECRET=my-cluster-secret
       {ok, _Pid} = macula_cluster_gossip:start_link(#{}).

### Network Requirements

- Nodes must be on the same multicast-enabled network - UDP port must be open in firewalls - Multicast must be enabled on network interfaces - For Docker, use `network_mode: host` or macvlan == Callbacks == Register a callback to receive cluster events: ``` {ok, _Pid} = macula_cluster_gossip:start_link(#{ callback => self() %% PID or {Module, Function} }). %% Receives: {macula_cluster, nodeup, Node} %% Receives: {macula_cluster, nodedown, Node}`''

# Summary

## Functions

broadcast_now()

Force an immediate broadcast.

broadcast_now(NameOrPid)

Force an immediate broadcast on a named instance.

get_connected()

Get the list of currently connected nodes.

get_connected(NameOrPid)

Get connected nodes from a named instance.

get_discovered()

Get the list of discovered nodes.

get_discovered(NameOrPid)

Get discovered nodes from a named instance.

start_link()

Start the gossip cluster strategy with default options.

start_link(Opts)

Start the gossip cluster strategy with options.

stop()

Stop the gossip cluster strategy.

stop(NameOrPid)

Stop a named gossip cluster strategy.

# Functions

# broadcast_now()

    -spec broadcast_now() -> ok.

Force an immediate broadcast.

# broadcast_now(NameOrPid)

    -spec broadcast_now(atom() | pid()) -> ok.

Force an immediate broadcast on a named instance.

# get_connected()

    -spec get_connected() -> [atom()].

Get the list of currently connected nodes.

# get_connected(NameOrPid)

    -spec get_connected(atom() | pid()) -> [atom()].

Get connected nodes from a named instance.

# get_discovered()

    -spec get_discovered() -> [atom()].

Get the list of discovered nodes.

# get_discovered(NameOrPid)

    -spec get_discovered(atom() | pid()) -> [atom()].

Get discovered nodes from a named instance.

# start_link()

    -spec start_link() -> {ok, pid()} | {error, term()}.

Start the gossip cluster strategy with default options.

# start_link(Opts)

    -spec start_link(map()) -> {ok, pid()} | {error, term()}.

Start the gossip cluster strategy with options.

Options: - multicast_addr: IPv4 multicast address (default {230, 1, 1, 251}) - port: UDP port (default 45892) - broadcast_interval: Milliseconds between broadcasts (default 1500) - multicast_ttl: Multicast TTL, 1 = same subnet (default 1) - secret: Optional binary secret for filtering broadcasts - callback: PID or {Module, Function} to receive cluster events

# stop()

    -spec stop() -> ok.

Stop the gossip cluster strategy.

# stop(NameOrPid)

    -spec stop(atom() | pid()) -> ok.

Stop a named gossip cluster strategy.