Skip to content

Commit

Permalink
Add documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@angrycub
angrycub committed Jun 1, 2023
1 parent fe44708 commit 0c244f4
Show file tree
Hide file tree
Showing 3 changed files with 190 additions and 19 deletions.
148 changes: 129 additions & 19 deletions website/content/api-docs/operator/raft.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
}

]
}
```

Expand All @@ -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.
Expand Down Expand Up @@ -100,18 +130,98 @@ 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>

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
57 changes: 57 additions & 0 deletions website/content/docs/commands/operator/raft/transfer-leadership.mdx
View file
Original file line number Diff line number Diff line change
@@ -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]
```

<Tip title="Required Permissions">
If ACLs are enabled, this command requires a management token.
</Tip>

## 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.

<Note>

Either `-peer-address` or `-peer-id` must be provided, but not both.

</Note>

[`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
4 changes: 4 additions & 0 deletions website/data/docs-nav-data.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -755,6 +755,10 @@
{
"title": "state",
"path": "commands/operator/raft/state"
},
{
"title": "transfer-leadership",
"path": "commands/operator/raft/transfer-leadership"
}
]
},
Expand Down

0 comments on commit 0c244f4

Please sign in to comment.