kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-07 19:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

[server] Directed leadership transfer CLI and API (#17383)

Browse Source 
* 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>
This commit is contained in:
Charlie Voiselle
2023-10-04 12:20:27 -04:00
committed by GitHub
parent c885c08640
commit 8a93ff3d2d
13 changed files with 1008 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
website/content/api-docs/operator/raft.mdx
View File

@@ -2,7 +2,7 @@
layout: api
page_title: Raft - Operator - HTTP API
description: |-
The /operator/raft endpoints provide tools for management of the Raft subsystem.
The /operator/raft endpoints provide tools for management of the Raft subsystem.
---
# Raft Operator HTTP API
@@ -34,26 +34,56 @@ The table below shows this endpoint's support for
### 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": 1,
"Servers": [
{
"Address": "127.0.0.1:4647",
"ID": "127.0.0.1:4647",
"Leader": true,
"Node": "bacon-mac.global",
"RaftProtocol": 2,
"Voter": true
}
]
"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
}
]
}
```
@@ -66,8 +96,8 @@ $ curl \
- `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.
- `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.
@@ -100,18 +130,100 @@ The table below shows this endpoint's support for
### Parameters
- `address` `(string: <optional>)` - Specifies the server to remove as
`ip:port`. This cannot be provided along with the `id` parameter.
- `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 server to remove as
`id`. This cannot be provided along with the `address` parameter.
- `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 \
https://localhost:4646/v1/operator/raft/peer?address=1.2.3.4:4646
--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