kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-04 17:35:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

Migrate operator APIs

Browse Source
This commit is contained in:
Seth Vargo
2017-05-26 19:17:15 -04:00
parent 681da3fea3
commit 1e05ae5353
2 changed files with 126 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
website/source/api/operator.html.md Normal file
View File

@@ -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: <required>)` - 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
```

166
website/source/docs/http/operator.html.md
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Query the status of a client node registered with Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/operator/raft/configuration`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">stale</span>
<span class="param-flags">optional</span>
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.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```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
}
```
</dd>
<dt>Field Reference</dt>
<dd>
<ul>
<li>
<span class="param">Servers</span>
The returned `Servers` array has information about the servers in the Raft
peer configuration. See the `Server` block for a description of its fields:
</li>
<li>
<span class="param">Index</span>
The `Index` value is the Raft corresponding to this configuration. The
latest configuration may not yet be committed if changes are in flight.
</li>
</ul>
`Server` Fields:
<ul>
<li>
<span class="param">ID</span>
`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.
</li>
<li>
<span class="param">Node</span>
`Node` is the node name of the server, as known to Nomad, or "(unknown)" if
the node is stale and not known.
</li>
<li>
<span class="param">Address</span>
`Address` is the IP:port for the server.
</li>
<li>
<span class="param">Leader</span>
`Leader` is either "true" or "false" depending on the server's role in the
Raft configuration.
</li>
<li>
<span class="param">Voter</span>
`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.
</li>
</ul>
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Remove the Nomad server with given address from the Raft configuration. The
return code signifies success or failure.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/v1/operator/raft/peer`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">address</span>
<span class="param-flags">required</span>
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.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>None</dd>
</dl>