{"id":13507581,"url":"https://github.com/bitwalker/libcluster","last_synced_at":"2025-05-08T23:35:04.098Z","repository":{"id":37270189,"uuid":"69692002","full_name":"bitwalker/libcluster","owner":"bitwalker","description":"Automatic cluster formation/healing for Elixir applications","archived":false,"fork":false,"pushed_at":"2025-01-09T09:28:41.000Z","size":217,"stargazers_count":2034,"open_issues_count":22,"forks_count":194,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-05-07T23:49:52.385Z","etag":null,"topics":["clustering","elixir","erlang-distribution"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitwalker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-30T18:33:32.000Z","updated_at":"2025-05-05T12:42:31.000Z","dependencies_parsed_at":"2023-02-14T12:17:06.622Z","dependency_job_id":"eaa6a5ff-d221-449b-8a60-fc1da36a8db4","html_url":"https://github.com/bitwalker/libcluster","commit_stats":{"total_commits":186,"total_committers":60,"mean_commits":3.1,"dds":0.6344086021505376,"last_synced_commit":"da2a8bb1710007d910bb093a2551444cde3543f6"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwalker%2Flibcluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwalker%2Flibcluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwalker%2Flibcluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwalker%2Flibcluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitwalker","download_url":"https://codeload.github.com/bitwalker/libcluster/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252974903,"owners_count":21834339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clustering","elixir","erlang-distribution"],"created_at":"2024-08-01T02:00:36.496Z","updated_at":"2025-05-08T23:35:04.071Z","avatar_url":"https://github.com/bitwalker.png","language":"Elixir","readme":"# libcluster\n\n[![Build Status](https://github.com/bitwalker/libcluster/workflows/elixir/badge.svg?branch=main)](https://github.com/bitwalker/libcluster/actions?query=workflow%3A%22elixir%22+branch%3Amain)\n[![Module Version](https://img.shields.io/hexpm/v/libcluster.svg)](https://hex.pm/packages/libcluster)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/libcluster/)\n[![Total Download](https://img.shields.io/hexpm/dt/libcluster.svg)](https://hex.pm/packages/libcluster)\n[![License](https://img.shields.io/hexpm/l/libcluster.svg)](https://github.com/bitwalker/libcluster/blob/main/LICENSE)\n[![Last Updated](https://img.shields.io/github/last-commit/bitwalker/libcluster.svg)](https://github.com/bitwalker/libcluster/commits/main)\n\nThis library provides a mechanism for automatically forming clusters of Erlang nodes, with\neither static or dynamic node membership. It provides a pluggable \"strategy\" system, with a variety of strategies\nprovided out of the box.\n\nYou can find supporting documentation [here](https://hexdocs.pm/libcluster).\n\n## Features\n\n- Automatic cluster formation/healing\n- Choice of multiple clustering strategies out of the box:\n  - Standard Distributed Erlang facilities (e.g. `epmd`, `.hosts.erlang`), which supports IP-based or DNS-based names\n  - Multicast UDP gossip, using a configurable port/multicast address,\n  - Kubernetes via its metadata API using via a configurable label selector and\n    node basename; or alternatively, using DNS.\n  - Rancher, via its [metadata API][rancher-api]\n- Easy to provide your own custom clustering strategies for your specific environment.\n- Easy to use provide your own distribution plumbing (i.e. something other than\n  Distributed Erlang), by implementing a small set of callbacks. This allows\n  `libcluster` to support projects like\n  [Partisan](https://github.com/lasp-lang/partisan).\n\n## Installation\n\n```elixir\ndefp deps do\n  [{:libcluster, \"~\u003e MAJ.MIN\"}]\nend\n```\n\nYou can determine the latest version by running `mix hex.info libcluster` in\nyour shell, or by going to the `libcluster` [page on Hex.pm](https://hex.pm/packages/libcluster).\n\n## Usage\n\nIt is easy to get started using `libcluster`, simply decide which strategy you\nwant to use to form a cluster, define a topology, and then start the `Cluster.Supervisor` module in\nthe supervision tree of an application in your Elixir system, as demonstrated below:\n\n```elixir\ndefmodule MyApp.App do\n  use Application\n\n  def start(_type, _args) do\n    topologies = [\n      example: [\n        strategy: Cluster.Strategy.Epmd,\n        config: [hosts: [:\"a@127.0.0.1\", :\"b@127.0.0.1\"]],\n      ]\n    ]\n    children = [\n      {Cluster.Supervisor, [topologies, [name: MyApp.ClusterSupervisor]]},\n      # ..other children..\n    ]\n    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)\n  end\nend\n```\n\nThe following section describes topology configuration in more detail.\n\n## Example Configuration\n\nYou can configure `libcluster` either in your Mix config file (`config.exs`) as\nshown below, or construct the keyword list structure manually, as shown in the\nprevious section. Either way, you need to pass the configuration to the\n`Cluster.Supervisor` module in it's start arguments. If you prefer to use Mix\nconfig files, then simply use `Application.get_env(:libcluster, :topologies)` to\nget the config that `Cluster.Supervisor` expects.\n\n```elixir\nconfig :libcluster,\n  topologies: [\n    epmd_example: [\n      # The selected clustering strategy. Required.\n      strategy: Cluster.Strategy.Epmd,\n      # Configuration for the provided strategy. Optional.\n      config: [hosts: [:\"a@127.0.0.1\", :\"b@127.0.0.1\"]],\n      # The function to use for connecting nodes. The node\n      # name will be appended to the argument list. Optional\n      connect: {:net_kernel, :connect_node, []},\n      # The function to use for disconnecting nodes. The node\n      # name will be appended to the argument list. Optional\n      disconnect: {:erlang, :disconnect_node, []},\n      # The function to use for listing nodes.\n      # This function must return a list of node names. Optional\n      list_nodes: {:erlang, :nodes, [:connected]},\n    ],\n    # more topologies can be added ...\n    gossip_example: [\n      # ...\n    ]\n  ]\n```\n\n## Strategy Configuration\n\nFor instructions on configuring each strategy included with `libcluster`, please\nvisit the docs on [HexDocs](https://hexdocs.pm/libcluster), and look at the\nmodule doc for the strategy you want to use. The authoritative documentation for\neach strategy is kept up to date with the module implementing it.\n\n## Clustering\n\nYou have a handful of choices with regards to cluster management out of the box:\n\n- `Cluster.Strategy.Epmd`, which relies on `epmd` to connect to a configured set\n  of hosts.\n- `Cluster.Strategy.LocalEpmd`, which relies on `epmd` to connect to discovered\n  nodes on the local host.\n- `Cluster.Strategy.ErlangHosts`, which uses the `.hosts.erlang` file to\n  determine which hosts to connect to.\n- `Cluster.Strategy.Gossip`, which uses multicast UDP to form a cluster between\n  nodes gossiping a heartbeat.\n- `Cluster.Strategy.Kubernetes`, which uses the Kubernetes Metadata API to query\n  nodes based on a label selector and basename.\n- `Cluster.Strategy.Kubernetes.DNS`, which uses DNS to join nodes under a shared\n  headless service in a given namespace.\n- `Cluster.Strategy.Rancher`, which like the Kubernetes strategy, uses a\n  metadata API to query nodes to cluster with.\n\nYou can also define your own strategy implementation, by implementing the\n`Cluster.Strategy` behavior. This behavior expects you to implement a\n`start_link/1` callback, optionally overriding `child_spec/1` if needed. You don't necessarily have\nto start a process as part of your strategy, but since it's very likely you will need to maintain some state, designing your\nstrategy as an OTP process (e.g. `GenServer`) is the ideal method, however any\nvalid OTP process will work. See the `Cluster.Strategy` module for details on\nthe callbacks you need to implement and the arguments they receive.\n\nIf you do not wish to use the default Erlang distribution protocol, you may provide an alternative means of connecting/\ndisconnecting nodes via the `connect` and `disconnect` configuration options, if not using Erlang distribution you must provide a `list_nodes` implementation as well.\nThey take a `{module, fun, args}` tuple, and append the node name being targeted to the `args` list. How to implement distribution in this way is left as an\nexercise for the reader, but I recommend taking a look at the [Firenest](https://github.com/phoenixframework/firenest) project\ncurrently under development. By default, `libcluster` uses Distributed Erlang.\n\n### Third-Party Strategies\n\nThe following list of third-party strategy implementations is not comprehensive,\nbut are known to exist.\n\n- [libcluster_ec2](https://github.com/kyleaa/libcluster_ec2) - EC2 clustering strategy based on tags\n- [libcluster_droplet](https://github.com/jsonmaur/libcluster-droplet) - Digital Ocean Droplet clustering strategy\n- [libcluster_consul](https://github.com/team-telnyx/libcluster_consul) - Consul clustering strategy\n- [libcluster_postgres](https://github.com/supabase/libcluster_postgres) - Postgres clustering strategy\n\n## Copyright and License\n\nCopyright (c) 2016 Paul Schoenfelder\n\nThis library is MIT licensed. See the\n[LICENSE.md](https://github.com/bitwalker/libcluster/blob/master/LICENSE.md) for details.\n\n[rancher-api]: http://rancher.com/docs/rancher/latest/en/rancher-services/metadata-service/\n","funding_links":[],"categories":["Cloud Infrastructure and Management","Elixir","\u003ca name=\"Elixir\"\u003e\u003c/a\u003eElixir"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwalker%2Flibcluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitwalker%2Flibcluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwalker%2Flibcluster/lists"}