Merge pull request #4614 from wyattanderson/wa-eligibility-docs

Add documentation for eligibility toggle endpoint

command/agent/node_endpoint.go

@@ -162,14 +162,14 @@ func (s *HTTPServer) nodeToggleEligibility(resp http.ResponseWriter, req *http.R
 		return nil, CodedError(405, ErrInvalidMethod)
 	}
 
-	var drainRequest structs.NodeUpdateEligibilityRequest
-	if err := decodeBody(req, &drainRequest); err != nil {
+	var eligibilityRequest structs.NodeUpdateEligibilityRequest
+	if err := decodeBody(req, &eligibilityRequest); err != nil {
 		return nil, CodedError(400, err.Error())
 	}
-	s.parseWriteRequest(req, &drainRequest.WriteRequest)
+	s.parseWriteRequest(req, &eligibilityRequest.WriteRequest)
 
 	var out structs.NodeEligibilityUpdateResponse
-	if err := s.agent.RPC("Node.UpdateEligibility", &drainRequest, &out); err != nil {
+	if err := s.agent.RPC("Node.UpdateEligibility", &eligibilityRequest, &out); err != nil {
 		return nil, err
 	}
 	setIndex(resp, out.Index)

website/source/api/nodes.html.md

@@ -875,6 +875,58 @@ $ curl \
 }
 ```
 
+## Toggle Node Eligibility
+
+This endpoint toggles the scheduling eligibility of the node.
+
+| Method  | Path                            | Produces                   |
+| ------- | ------------------------------- | -------------------------- |
+| `POST`  | `/v1/node/:node_id/eligibility` | `application/json`         |
+
+The table below shows this endpoint's support for
+[blocking queries](/api/index.html#blocking-queries) and
+[required ACLs](/api/index.html#acls).
+
+| Blocking Queries | ACL Required       |
+| ---------------- | ------------------ |
+| `NO`             | `node:write`       |
+
+### Parameters
+
+- `:node_id` `(string: <required>)`- Specifies the UUID of the node. This must
+  be the full UUID, not the short 8-character one. This is specified as part of
+  the path.
+
+- `Eligibility` `(string: <required>)` - Either `eligible` or `ineligible`.
+
+### Sample Payload
+
+```json
+{
+    "Eligibility": "ineligible"
+}
+```
+
+### Sample Request
+
+```text
+$ curl \
+    -XPOST \
+    --data @eligibility.json \
+    http://localhost:4646/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/eligibility
+```
+
+### Sample Response
+
+```json
+{
+  "EvalCreateIndex": 0,
+  "EvalIDs": null,
+  "Index": 3742,
+  "NodeModifyIndex": 3742
+}
+```
+
 #### Field Reference
 
 - Events - A list of the last 10 node events for this node. A node event is a

website/source/docs/commands/node/eligibility.html.md.erb

@@ -10,8 +10,8 @@ description: >
 # Command: node eligibility
 
 The `node eligibility` command is used to toggle scheduling eligibility for a
-given node. By default node's are eligible for scheduling meaning they can
-receive placements and run new allocations. Node's that have their scheduling
+given node. By default nodes are eligible for scheduling meaning they can
+receive placements and run new allocations. Nodes that have their scheduling
 elegibility disabled are ineligibile for new placements.
 
 The [`node drain`][drain] command automatically disables eligibility. Disabling
@@ -20,7 +20,7 @@ a drain restore eligibility by default.
 Disable scheduling eligibility is useful when draining a set of nodes: first
 disable eligibility on each node that will be drained. Then drain each node.
 If you just drain each node allocations may get rescheduled multiple times as
-they get placed on node's about to be drained!
+they get placed on nodes about to be drained!
 
 Disabling scheduling eligibility may also be useful when investigating poorly
 behaved nodes. It allows operators to investigate the current state of a node