mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
27caae2b2a
In Nomad 1.4.0 we removed support for Raft Protocol v2 entirely. But the `Operator.RemoveRaftPeerByAddress` RPC handler was left in place, along with its supporting HTTP API and command line flags. Using this API will always result in the Raft library error "operation not supported with current protocol version". Unfortunately it's still possible in unit tests to exercise this code path, and these tests are quite flaky. This changeset turns the RPC handler and HTTP API into a no-op, removes the associated command line flags, and removes the flaky tests. I've also cleaned up the test for `RemoveRaftPeerByID` to consolidate test servers and use `shoenig/test`. Fixes: https://hashicorp.atlassian.net/browse/NET-12413 Ref: https://github.com/hashicorp/nomad/pull/13467 Ref: https://developer.hashicorp.com/nomad/docs/upgrade/upgrade-specific#raft-protocol-version-2-unsupported Ref: https://github.com/hashicorp/nomad-enterprise/actions/runs/13201513025/job/36855234398?pr=2302
220 lines
6.0 KiB
Plaintext
220 lines
6.0 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
|
|
|
|
- `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.
|
|
|
|
### 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
|