mirror of https://github.com/status-im/consul.git
130 lines
4.6 KiB
Plaintext
130 lines
4.6 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: Operator Raft'
|
|
description: >
|
|
The operator raft subcommand is used to view and modify Consul's Raft
|
|
configuration.
|
|
---
|
|
|
|
# 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.
|
|
|
|
```text
|
|
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](/api-docs/status#list-raft-peers)
|
|
|
|
This command displays the current Raft peer configuration.
|
|
|
|
The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of
|
|
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/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]`
|
|
|
|
The output looks like this:
|
|
|
|
```text
|
|
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.
|
|
|
|
#### Command Options
|
|
|
|
- `-stale` - Enables non-leader servers to provide cluster state information.
|
|
If the cluster is in an outage state without a leader,
|
|
we recommend setting this option to `true.
|
|
Default is `false`.
|
|
|
|
## remove-peer
|
|
|
|
Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/raft/peer](/api-docs/operator/raft#delete-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`](/commands/members) command, it is preferable to
|
|
clean up by simply running
|
|
[`consul force-leave`](/commands/force-leave)
|
|
instead of this command.
|
|
|
|
The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of
|
|
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/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.
|
|
|
|
## transfer-leader
|
|
|
|
Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/raft/transfer-leader](/api-docs/operator/raft#transfer-raft-leadership)
|
|
|
|
This command transfers Raft leadership to another server agent. If an `id` is provided, Consul transfers leadership to the server with that id.
|
|
|
|
Use this command to change leadership without restarting the leader node, which maintains quorum and workload capacity.
|
|
|
|
The table below shows this command's [required ACLs](/api-docs#authentication). Configuration of
|
|
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
| ACL Required |
|
|
| ---------------- |
|
|
| `operator:write` |
|
|
|
|
Usage: `consul operator raft transfer-leader -id="server id"`
|
|
|
|
- `-id` - Specifies the node ID of the raft peer to transfer leadership to.
|
|
If empty, leadership transfers to a random server agent.
|
|
|
|
The return code indicates success or failure.
|