diff --git a/website/source/api/operator.html.md b/website/source/api/operator.html.md new file mode 100644 index 000000000..7c0a2054f --- /dev/null +++ b/website/source/api/operator.html.md @@ -0,0 +1,126 @@ +--- +layout: api +page_title: Operator - HTTP API +sidebar_current: api-operator +description: |- + The /operator endpoints provides cluster-level tools for Nomad operators, such + as interacting with the Raft subsystem. +--- +# /v1/operator + +The `/operator` endpoint provides cluster-level tools for Nomad operators, such +as interacting with the Raft subsystem. + +~> Use this interface with extreme caution, as improper use could lead to a +Nomad outage and even loss of data. + +See the [Outage Recovery](/guides/outage.html) guide for some examples of how +these capabilities are used. For a CLI to perform these operations manually, +please see the documentation for the +[`nomad operator`](/docs/commands/operator-index.html) command. + + +## 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](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `NO` | `all` | `none` | + +### Parameters + +- `stale` - Specifies if the cluster should respond without an active leader. + This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/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", + "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. This is the same as the `Address` + but may be upgraded to a GUID in a future version of Nomad. + + - `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](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `NO` | `all` | `none` | + +### Parameters + +- `address` `(string: )` - Specifies the server to remove as + `ip:port`. This may be provided multiple times and is provided as a + querystring parameter. + +- `stale` - Specifies if the cluster should respond without an active leader. + This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + --request DELETE \ + https://nomad.rocks/v1/operator/raft/peer?address=1.2.3.4 +``` diff --git a/website/source/docs/http/operator.html.md b/website/source/docs/http/operator.html.md deleted file mode 100644 index 43f8ba6e3..000000000 --- a/website/source/docs/http/operator.html.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/operator/" -sidebar_current: "docs-http-operator" -description: > - The '/v1/operator/' endpoints provides cluster-level tools for Nomad - operators. ---- - -# /v1/operator - -The Operator endpoint provides cluster-level tools for Nomad operators, such -as interacting with the Raft subsystem. This was added in Nomad 0.5.5 - -~> Use this interface with extreme caution, as improper use could lead to a - Nomad outage and even loss of data. - -See the [Outage Recovery](/guides/outage.html) guide for some examples of how -these capabilities are used. For a CLI to perform these operations manually, please -see the documentation for the [`nomad operator`](/docs/commands/operator-index.html) -command. - -By default, the agent's local region is used; another region can be specified -using the `?region=` query parameter. - -## GET - -
-
Description
-
- Query the status of a client node registered with Nomad. -
- -
Method
-
GET
- -
URL
-
`/v1/operator/raft/configuration`
- -
Parameters
-
-
    -
  • - stale - optional - If the cluster doesn't currently have a leader an error will be - returned. You can use the `?stale` query parameter to read the Raft - configuration from any of the Nomad servers. -
    • -
-
- -
Returns
-
- - ```javascript -{ - "Servers": [ - { - "ID": "127.0.0.1:4647", - "Node": "alice", - "Address": "127.0.0.1:4647", - "Leader": true, - "Voter": true - }, - { - "ID": "127.0.0.2:4647", - "Node": "bob", - "Address": "127.0.0.2:4647", - "Leader": false, - "Voter": true - }, - { - "ID": "127.0.0.3:4647", - "Node": "carol", - "Address": "127.0.0.3:4647", - "Leader": false, - "Voter": true - } - ], - "Index": 22 -} - ``` - -
- -
Field Reference
-
- -
    -
  • - Servers - The returned `Servers` array has information about the servers in the Raft - peer configuration. See the `Server` block for a description of its fields: -
    • -
  • - Index - The `Index` value is the Raft corresponding to this configuration. The - latest configuration may not yet be committed if changes are in flight. -
    • -
- - `Server` Fields: -
    -
  • - ID - `ID` is 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. -
    • -
  • - Node - `Node` is the node name of the server, as known to Nomad, or "(unknown)" if - the node is stale and not known. -
    • -
  • - Address - `Address` is the IP:port for the server. -
    • -
  • - Leader - `Leader` is either "true" or "false" depending on the server's role in the - Raft configuration. -
    • -
  • - Voter - `Voter` 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. -
    • -
- -
-
- - -## DELETE - -
-
Description
-
- Remove the Nomad server with given address from the Raft configuration. The - return code signifies success or failure. -
- -
Method
-
DELETE
- -
URL
-
`/v1/operator/raft/peer`
- -
Parameters
-
-
    -
  • - address - required - The address specifies the server to remove and is given as an `IP:port`. - The port number is usually 4647, unless configured otherwise. Nothing is - required in the body of the request. -
    • -
-
- -
Returns
-
None
- -