Package io.atomix.raft.cluster

Interface RaftCluster

All Known Implementing Classes:
RaftClusterContext
public interface RaftCluster
Raft server cluster API.

This class provides the view of the Raft cluster from the perspective of a single server. When a RaftServer is started, the server will form a cluster with other servers. Each Raft cluster consists of some set of members, and each RaftMember represents a single server in the cluster. Users can use the Cluster to react to state changes in the underlying Raft algorithm via the various listeners. 


 server.cluster().onJoin(member -> {
   System.out.println(member.address() + " joined the cluster!");
 });
Membership exposed via this interface is provided from the perspective of the local server and may not necessarily be consistent with cluster membership from the perspective of other nodes. The only consistent membership list is on the leader node.

Cluster management

Users can use the Cluster to manage the Raft cluster membership. Typically, servers join the cluster by calling RaftServer.bootstrap(MemberId...). 


 server.cluster().onJoin(member -> {
   member.remove().thenRun(() -> System.out.println("Removed " + member.address() + " from the cluster!"));
 });
When a member is removed from the cluster, the configuration change removing the member will be replicated to all the servers in the cluster and persisted to disk. Once a member has been removed, for that member to rejoin the cluster it must fully restart and request to rejoin the cluster. Cluster configurations are stored on disk.

Additionally, members can be promoted and demoted by any other member of the cluster. When a member state is changed, a cluster configuration change request is sent to the cluster leader where it's logged and replicated through the Raft consensus algorithm. During the configuration change, servers' cluster configurations will be updated. Once the configuration change is complete, it will be persisted to disk on all servers and is guaranteed not to be lost even in the event of a full cluster shutdown.

  • Method Details

    • bootstrap

      default CompletableFuture<Void> bootstrap(MemberId... cluster)
      Bootstraps the cluster.

      Bootstrapping the cluster results in a new cluster being formed with the provided configuration. The initial nodes in a cluster must always be bootstrapped. This is necessary to prevent split brain. If the provided configuration is empty, the local server will form a single-node cluster.

      Only RaftMember.Type.ACTIVE members can be included in a bootstrap configuration. If the local server is not initialized as an active member, it cannot be part of the bootstrap configuration for the cluster.

      When the cluster is bootstrapped, the local server will be transitioned into the active state and begin participating in the Raft consensus algorithm. When the cluster is first bootstrapped, no leader will exist. The bootstrapped members will elect a leader amongst themselves.

      It is critical that all servers in a bootstrap configuration be started with the same exact set of members. Bootstrapping multiple servers with different configurations may result in split brain.

      The CompletableFuture returned by this method will be completed once the cluster has been bootstrapped, a leader has been elected, and the leader has been notified of the local server's client configurations.

      Parameters:
      cluster - The bootstrap cluster configuration.
      Returns:
      A completable future to be completed once the cluster has been bootstrapped.

    • bootstrap

      CompletableFuture<Void> bootstrap(Collection<MemberId> cluster)
      Bootstraps the cluster.

      Bootstrapping the cluster results in a new cluster being formed with the provided configuration. The initial nodes in a cluster must always be bootstrapped. This is necessary to prevent split brain. If the provided configuration is empty, the local server will form a single-node cluster.

      Only RaftMember.Type.ACTIVE members can be included in a bootstrap configuration. If the local server is not initialized as an active member, it cannot be part of the bootstrap configuration for the cluster.

      When the cluster is bootstrapped, the local server will be transitioned into the active state and begin participating in the Raft consensus algorithm. When the cluster is first bootstrapped, no leader will exist. The bootstrapped members will elect a leader amongst themselves.

      It is critical that all servers in a bootstrap configuration be started with the same exact set of members. Bootstrapping multiple servers with different configurations may result in split brain.

      The CompletableFuture returned by this method will be completed once the cluster has been bootstrapped, a leader has been elected, and the leader has been notified of the local server's client configurations.

      Parameters:
      cluster - The bootstrap cluster configuration.
      Returns:
      A completable future to be completed once the cluster has been bootstrapped.

    • join

      CompletableFuture<Void> join(Collection<MemberId> cluster)

    • getMember

      RaftMember getMember(MemberId id)
      Returns a member by ID.

      The returned RaftMember is referenced by the unique RaftMember.memberId().

      Parameters:
      id - The member ID.
      Returns:
      The member or null if no member with the given id exists.

    • getLocalMember

      RaftMember getLocalMember()
      Returns the local cluster member.
      Returns:
      The local cluster member.

    • getMembers

      Collection<RaftMember> getMembers()
      Returns a collection of all cluster members.

      The returned members are representative of the last configuration known to the local server. Over time, the cluster configuration may change. In the event of a membership change, the returned Collection will not be modified, but instead a new collection will be created. Similarly, modifying the returned collection will have no impact on the cluster membership.

      Returns:
      A collection of all cluster members.