Consul Operator Raft

Command: consul operator raft

The Raft operator command is used to interact with Consul's Raft subsystem. The command can be used to verify Raft peers or in rare cases to recover quorum by removing invalid peers.

Usage: consul operator raft <subcommand> [options]

The Raft operator command is used to interact with Consul's Raft subsystem. The
command can be used to verify Raft peers or in rare cases to recover quorum by
removing invalid peers.

Subcommands:

    list-peers     Display the current Raft peer configuration
    remove-peer    Remove a Consul server from the Raft configuration

list-peers

Corresponding HTTP API Endpoint: [GET] /v1/status/peers

This command displays the current Raft peer configuration.

The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.

ACL Required
`none`

Usage: consul operator raft list-peers -stale=[true|false]

-stale - Optional and defaults to "false" which means the leader provides the result. If the cluster is in an outage state without a leader, you may need to set this to "true" to get the configuration from a non-leader server.

The output looks like this:

Node     ID              Address         State     Voter  RaftProtocol
alice    127.0.0.1:8300  127.0.0.1:8300  follower  true   2
bob      127.0.0.2:8300  127.0.0.2:8300  leader    true   3
carol    127.0.0.3:8300  127.0.0.3:8300  follower  true   2

Node is the node name of the server, as known to Consul, or "(unknown)" if the node is stale and not known.

ID is the ID of the server. This is the same as the Address in Consul 0.7 but may be upgraded to a GUID in a future version of Consul.

Address is the IP:port for the server.

State is either "follower" or "leader" depending on the server's role in the Raft configuration.

Voter is "true" or "false", indicating if the server has a vote in the Raft configuration.

remove-peer

Corresponding HTTP API Endpoint: [DELETE] /v1/operator/raft/peer

This command removes the Consul server with given address from the Raft configuration.

There are rare cases where a peer may be left behind in the Raft configuration even though the server is no longer present and known to the cluster. This command can be used to remove the failed server so that it is no longer affects the Raft quorum. If the server still shows in the output of the consul members command, it is preferable to clean up by simply running consul force-leave instead of this command.

The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.

ACL Required
`operator:write`

Usage: consul operator raft remove-peer -address="IP:port"

-address - "IP:port" for the server to remove. The port number is usually 8300, unless configured otherwise.
-id - ID of the server to remove.

The return code will indicate success or failure.