mirror of https://github.com/status-im/consul.git
182 lines
6.2 KiB
Plaintext
182 lines
6.2 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Raft - Operator - HTTP API
|
|
description: |-
|
|
The /operator/raft endpoints provide tools for management of Raft the
|
|
consensus subsystem and cluster quorum.
|
|
---
|
|
|
|
# Raft Operator HTTP API
|
|
|
|
The `/operator/raft` endpoints provide tools for management of Raft the
|
|
consensus subsystem and cluster quorum.
|
|
|
|
Please see the [Consensus Protocol Guide](/consul/docs/architecture/consensus) for
|
|
more information about Raft consensus protocol and its use.
|
|
|
|
## Read Configuration
|
|
|
|
This endpoint reads the current raft configuration.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------ | ------------------ |
|
|
| `GET` | `/operator/raft/configuration` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | --------------------- | ------------- | --------------- |
|
|
| `NO` | `default` and `stale` | `none` | `operator:read` |
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query.
|
|
This parameter defaults to the datacenter of the agent being queried.
|
|
|
|
- `stale` `(bool: false)` - If the cluster does not currently have a leader an
|
|
error will be returned. You can use the `?stale` query parameter to read the
|
|
Raft configuration from any of the Consul servers. Not setting this will choose
|
|
the default consistency mode which will forward the request to the leader for
|
|
processing but not re-confirm the server is still the leader before returning
|
|
results. See [default consistency](/consul/api-docs/features/consistency#default) for more details.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/operator/raft/configuration
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Servers": [
|
|
{
|
|
"ID": "127.0.0.1:8300",
|
|
"Node": "alice",
|
|
"Address": "127.0.0.1:8300",
|
|
"Leader": true,
|
|
"Voter": true
|
|
},
|
|
{
|
|
"ID": "127.0.0.2:8300",
|
|
"Node": "bob",
|
|
"Address": "127.0.0.2:8300",
|
|
"Leader": false,
|
|
"Voter": true
|
|
},
|
|
{
|
|
"ID": "127.0.0.3:8300",
|
|
"Node": "carol",
|
|
"Address": "127.0.0.3:8300",
|
|
"Leader": false,
|
|
"Voter": true
|
|
}
|
|
],
|
|
"Index": 22
|
|
}
|
|
```
|
|
|
|
- `Servers` is has information about the servers in the Raft peer configuration:
|
|
|
|
- `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.
|
|
|
|
- `Node` is the node name of the server, as known to Consul, or "(unknown)" if
|
|
the node is stale and not known.
|
|
|
|
- `Address` is the IP:port for the server.
|
|
|
|
- `Leader` is either "true" or "false" 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. Future versions of Consul may add support for non-voting
|
|
servers.
|
|
|
|
- `Index` is the Raft corresponding to this configuration. The latest
|
|
configuration may not yet be committed if changes are in flight.
|
|
|
|
## Delete Raft Peer
|
|
|
|
This endpoint 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
|
|
endpoint can be used to remove the failed server so that it is no longer affects
|
|
the Raft quorum.
|
|
|
|
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
|
|
write privileges.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | --------------------- | ------------------ |
|
|
| `DELETE` | `/operator/raft/peer` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul operator raft remove-peer`](/consul/commands/operator/raft#remove-peer).
|
|
|
|
### Query Parameters
|
|
|
|
- `id|address` `(string: <required>)` - Specifies the ID or address (IP:port) of the raft peer to remove.
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
"http://127.0.0.1:8500/v1/operator/raft/peer?address=1.2.3.4:5678"
|
|
```
|
|
|
|
## Transfer Raft Leadership
|
|
|
|
This endpoint transfers the Raft leadership from the current leader to a different Raft peer.
|
|
The new leader is selected at random unless explicitly specified with the `id` parameter.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | ------------------------------- | ------------------ |
|
|
| `POST` | `/operator/raft/transfer-leader` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ---------------- |
|
|
| `NO` | `none` | `none` | `operator:write` |
|
|
|
|
The corresponding CLI command is [`consul operator raft transfer-leader`](/consul/commands/operator/raft#transfer-leader).
|
|
|
|
### Query Parameters
|
|
|
|
- `id` `(string: "")` - Specifies the node ID of the Raft peer to transfer leadership to.
|
|
If empty, leadership transfers to a random server agent.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
"http://127.0.0.1:8500/v1/operator/raft/transfer-leader?id=09cfc046-e74a-ad49-1aad-c2161b7fe677"
|
|
```
|