open-nomad/website/content/api-docs/operator/raft.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

118 lines
3.4 KiB
Plaintext
Raw Normal View History

---
layout: api
page_title: Raft - Operator - HTTP API
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](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/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](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/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]: /nomad/docs/concepts/consensus