mirror of
https://github.com/kemko/nomad.git
synced 2026-01-02 16:35:44 +03:00
8a93ff3d2d
* Add directed leadership transfer func * Add leadership transfer RPC endpoint * Add ACL tests for leadership-transfer endpoint * Add HTTP API route and implementation * Add to Go API client * Implement CLI command * Add documentation * Add changelog Co-authored-by: Tim Gross <tgross@hashicorp.com>
230 lines
6.3 KiB
Plaintext
230 lines
6.3 KiB
Plaintext
---
|
|
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
|
|
|
|
<Tabs>
|
|
<Tab heading="Nomad CLI">
|
|
|
|
```shell-session
|
|
$ nomad operator api /v1/operator/raft/configuration
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="curl">
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/operator/raft/configuration
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 0,
|
|
"Servers": [
|
|
{
|
|
"Address": "10.1.0.10:4647",
|
|
"ID": "c13f9998-a0f3-d765-0b52-55a0b3ce5f88",
|
|
"Leader": false,
|
|
"Node": "node1.global",
|
|
"RaftProtocol": "3",
|
|
"Voter": true
|
|
},
|
|
{
|
|
"Address": "10.1.0.20:4647",
|
|
"ID": "d7927f2b-067f-45a4-6266-af8bb84de082",
|
|
"Leader": true,
|
|
"Node": "node2.global",
|
|
"RaftProtocol": "3",
|
|
"Voter": true
|
|
},
|
|
{
|
|
"Address": "10.1.0.30:4647",
|
|
"ID": "00d56ef8-938e-abc3-6f8a-f8ac80a80fb9",
|
|
"Leader": false,
|
|
"Node": "node3.global",
|
|
"RaftProtocol": "3",
|
|
"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. For Raft protocol v2, this is the
|
|
same as the `Address`. Raft protocol v3 uses GUIDs as the ID.
|
|
|
|
- `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 Raft **Address** of the
|
|
server to remove as provided in the output of `/v1/operator/raft/configuration`
|
|
API endpoint or the `nomad operator raft list-peers` command.
|
|
|
|
- `id` `(string: <optional>)` - Specifies the Raft **ID** of the server to
|
|
remove as provided in the output of `/v1/operator/raft/configuration`
|
|
API endpoint or the `nomad operator raft list-peers` command.
|
|
|
|
<Note>
|
|
|
|
Either `address` or `id` must be provided, but not both.
|
|
|
|
</Note>
|
|
|
|
### Sample Request
|
|
|
|
|
|
<Tabs>
|
|
<Tab heading="Nomad CLI">
|
|
|
|
```shell-session
|
|
$ nomad operator api -X DELETE \
|
|
/v1/operator/raft/peer?address=1.2.3.4:4647
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="curl">
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
--header "X-Nomad-Token: ${NOMAD_TOKEN}"
|
|
https://127.0.0.1:4646/v1/operator/raft/peer?address=1.2.3.4:4647
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Transfer Leadership to another Raft Peer
|
|
|
|
This endpoint tells the current cluster leader to transfer leadership
|
|
to the Nomad server with given address or ID in the Raft
|
|
configuration. The return code signifies success or failure.
|
|
|
|
| Method | Path | Produces |
|
|
| ------------------- | --------------------------------------- | ------------------ |
|
|
| `PUT` <br /> `POST` | `/v1/operator/raft/transfer-leadership` | `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 Raft **Address** of the
|
|
target server as provided in the output of `/v1/operator/raft/configuration`
|
|
API endpoint or the `nomad operator raft list-peers` command.
|
|
|
|
- `id` `(string: <optional>)` - Specifies the Raft **ID** of the target server
|
|
as provided in the output of `/v1/operator/raft/configuration` API endpoint or
|
|
the `nomad operator raft list-peers` command.
|
|
|
|
<Note>
|
|
|
|
- The cluster must be running Raft protocol v3 or greater on all server members.
|
|
|
|
- Either `address` or `id` must be provided, but not both.
|
|
|
|
</Note>
|
|
|
|
### Sample Requests
|
|
|
|
<Tabs>
|
|
<Tab heading="Nomad CLI">
|
|
|
|
```shell-session
|
|
$ nomad operator api -X PUT \
|
|
"/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647"
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="curl">
|
|
|
|
```shell-session
|
|
$ curl --request PUT \
|
|
--header "X-Nomad-Token: ${NOMAD_TOKEN}"
|
|
"https://127.0.0.1:4646/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647"
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
[consensus protocol guide]: /nomad/docs/concepts/consensus
|