diff --git a/website/content/api-docs/operator/raft.mdx b/website/content/api-docs/operator/raft.mdx index b6313223f07..84d673bd0c0 100644 --- a/website/content/api-docs/operator/raft.mdx +++ b/website/content/api-docs/operator/raft.mdx @@ -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 + + + +```shell-session +$ nomad operator api /v1/operator/raft/configuration +``` + + + + ```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 - } - ] + "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,98 @@ The table below shows this endpoint's support for ### Parameters -- `address` `(string: )` - Specifies the server to remove as - `ip:port`. This cannot be provided along with the `id` parameter. +- `address` `(string: )` - 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: )` - Specifies the server to remove as - `id`. This cannot be provided along with the `address` parameter. +- `id` `(string: )` - 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. + + + + Either `address` or `id` must be provided, but not both. + + ### Sample Request + + + + +```shell-session +$ nomad operator api -X DELETE \ + /v1/operator/raft/peer?address=1.2.3.4:4647 +``` + + + + ```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 ``` + + + +## 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`
`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: )` - 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: )` - 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. + + + + Either `address` or `id` must be provided, but not both. + + + +### Sample Requests + + + + +```shell-session +$ nomad operator api -X PUT \ + "/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647" +``` + + + + +```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" +``` + + + + [consensus protocol guide]: /nomad/docs/concepts/consensus diff --git a/website/content/docs/commands/operator/raft/transfer-leadership.mdx b/website/content/docs/commands/operator/raft/transfer-leadership.mdx new file mode 100644 index 00000000000..0520b530b9b --- /dev/null +++ b/website/content/docs/commands/operator/raft/transfer-leadership.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: 'Commands: operator raft transfer-leadership' +description: | + Transfer leadership to a specific a Nomad server. +--- + +# Command: operator raft transfer-leadership + +Transfer leadership from the current leader to the given server member. + +While performing a [rolling upgrade][] of your Nomad cluster, it might be +advisable to transfer leadership to a specific node in the cluster. For example, +setting the leader to the first upgraded server in the cluster can prevent +leadership churn as you upgrade the remaining server nodes. + +The target server's ID or address:port are required and can be obtained by +running the [`nomad operator raft list-peers`][] command or by calling the +[Read Raft Configuration][] API endpoint. + +For an API to perform these operations programmatically, please see the +documentation for the [Operator][] endpoint. + +## Usage + +```plaintext +nomad operator raft transfer-leadership [options] +``` + + +If ACLs are enabled, this command requires a management token. + + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Transfer Leadership Options + +- `-peer-address`: Specifies the Raft **Address** of the target server as + provided in the output of the [`nomad operator raft list-peers`][] command or + the [Read Raft Configuration] API endpoint. + +- `-peer-id`: Specifies the Raft **ID** of the target server as provided in the + output of the [`nomad operator raft list-peers`][] command or the + [Read Raft Configuration] API endpoint. + + + + Either `-peer-address` or `-peer-id` must be provided, but not both. + + + +[`nomad operator raft list-peers`]: /nomad/docs/commands/operator/raft/list-peers 'Nomad operator raft list-peers command' +[operator]: /nomad/api-docs/operator 'Nomad Operator API' +[rolling upgrade]: /nomad/docs/upgrade#upgrade-process +[Read Raft Configuration]: /nomad/api-docs/operator/raft#read-raft-configuration diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 84849322a6e..a227484ec92 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -792,6 +792,10 @@ { "title": "state", "path": "commands/operator/raft/state" + }, + { + "title": "transfer-leadership", + "path": "commands/operator/raft/transfer-leadership" } ] },