119 lines
3.4 KiB
Plaintext
119 lines
3.4 KiB
Plaintext
|
---
|
||
|
|
layout: api
|
||
|
|
page_title: Raft - Operator - HTTP API
|
||
|
|
sidebar_title: Raft
|
||
|
|
description: |-
|
||
|
|
The /operator/raft endpoints provide tools for management of the Raft subsystem.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Raft Operator HTTP API
|
||
|
|
|
||
|
|
The `/operator/raft` endpoints provide tools for management of the Raft subsystem.
|
||
|
|
|
||
|
|
Please see the [Consensus Protocol Guide] for more information about Raft consensus protocol and its use.
|
||
|
|
|
||
|
|
## Read Raft Configuration
|
||
|
|
|
||
|
|
This endpoint queries the status of a client node registered with Nomad.
|
||
|
|
|
||
|
|
| Method | Path | Produces |
|
||
|
|
| ------ | --------------------------------- | ------------------ |
|
||
|
|
| `GET` | `/v1/operator/raft/configuration` | `application/json` |
|
||
|
|
|
||
|
|
The table below shows this endpoint's support for
|
||
|
|
[blocking queries](/api-docs#blocking-queries) and
|
||
|
|
[required ACLs](/api-docs#acls).
|
||
|
|
|
||
|
|
| Blocking Queries | ACL Required |
|
||
|
|
| ---------------- | ------------ |
|
||
|
|
| `NO` | `management` |
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
|
||
|
|
- `stale` - Specifies if the cluster should respond without an active leader.
|
||
|
|
This is specified as a query string parameter.
|
||
|
|
|
||
|
|
### Sample Request
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ curl \
|
||
|
|
https://localhost:4646/v1/operator/raft/configuration
|
||
|
|
```
|
||
|
|
|
||
|
|
### Sample Response
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"Index": 1,
|
||
|
|
"Servers": [
|
||
|
|
{
|
||
|
|
"Address": "127.0.0.1:4647",
|
||
|
|
"ID": "127.0.0.1:4647",
|
||
|
|
"Leader": true,
|
||
|
|
"Node": "bacon-mac.global",
|
||
|
|
"RaftProtocol": 2,
|
||
|
|
"Voter": true
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Field Reference
|
||
|
|
|
||
|
|
- `Index` `(int)` - The `Index` value is the Raft corresponding to this
|
||
|
|
configuration. The latest configuration may not yet be committed if changes
|
||
|
|
are in flight.
|
||
|
|
|
||
|
|
- `Servers` `(array: Server)` - The returned `Servers` array has information
|
||
|
|
about the servers in the Raft peer configuration.
|
||
|
|
|
||
|
|
- `ID` `(string)` - The ID of the server. This is the same as the `Address`
|
||
|
|
but may be upgraded to a GUID in a future version of Nomad.
|
||
|
|
|
||
|
|
- `Node` `(string)` - The node name of the server, as known to Nomad, or
|
||
|
|
`"(unknown)"` if the node is stale and not known.
|
||
|
|
|
||
|
|
- `Address` `(string)` - The `ip:port` for the server.
|
||
|
|
|
||
|
|
- `Leader` `(bool)` - is either "true" or "false" depending on the server's
|
||
|
|
role in the Raft configuration.
|
||
|
|
|
||
|
|
- `Voter` `(bool)` - is "true" or "false", indicating if the server has a vote
|
||
|
|
in the Raft configuration. Future versions of Nomad may add support for
|
||
|
|
non-voting servers.
|
||
|
|
|
||
|
|
## Remove Raft Peer
|
||
|
|
|
||
|
|
This endpoint removes a Nomad server with given address from the Raft
|
||
|
|
configuration. The return code signifies success or failure.
|
||
|
|
|
||
|
|
| Method | Path | Produces |
|
||
|
|
| -------- | ------------------------ | ------------------ |
|
||
|
|
| `DELETE` | `/v1/operator/raft/peer` | `application/json` |
|
||
|
|
|
||
|
|
The table below shows this endpoint's support for
|
||
|
|
[blocking queries](/api-docs#blocking-queries) and
|
||
|
|
[required ACLs](/api-docs#acls).
|
||
|
|
|
||
|
|
| Blocking Queries | ACL Required |
|
||
|
|
| ---------------- | ------------ |
|
||
|
|
| `NO` | `management` |
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
|
||
|
|
- `address` `(string: <optional>)` - Specifies the server to remove as
|
||
|
|
`ip:port`. This cannot be provided along with the `id` parameter.
|
||
|
|
|
||
|
|
- `id` `(string: <optional>)` - Specifies the server to remove as
|
||
|
|
`id`. This cannot be provided along with the `address` parameter.
|
||
|
|
|
||
|
|
### Sample Request
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ curl \
|
||
|
|
--request DELETE \
|
||
|
|
https://localhost:4646/v1/operator/raft/peer?address=1.2.3.4:4646
|
||
|
|
```
|
||
|
|
|
||
|
|
[Consensus Protocol Guide]: /docs/internals/consensus
|