mirror of
https://github.com/kemko/nomad.git
synced 2026-01-05 01:45:44 +03:00
document new scaling APIs in the API section
This commit is contained in:
Chris Baker
@@ -24,6 +24,7 @@ export default [
|
||||
'plugins',
|
||||
'quotas',
|
||||
'regions',
|
||||
'scaling-policies',
|
||||
'search',
|
||||
'sentinel-policies',
|
||||
'status',
|
||||
|
||||
@@ -1726,3 +1726,135 @@ $ curl \
|
||||
"JobModifyIndex": 34
|
||||
}
|
||||
```
|
||||
|
||||
## Read Job Scale Status <sup>beta 0.11</sup>
|
||||
|
||||
This endpoint reads scale information about a job.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------- | ------------------ |
|
||||
| `GET` | `/v1/job/:job_id/scale` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api#blocking-queries) and
|
||||
[required ACLs](/api#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `YES` | `namespace:read-job-scaling` or `namespace:read-job`|
|
||||
|
||||
### Parameters
|
||||
|
||||
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
|
||||
the job file during submission). This is specified as part of the path.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell
|
||||
$ curl \
|
||||
https://localhost:4646/v1/job/my-job/scale
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"JobCreateIndex": 10,
|
||||
"JobID": "example",
|
||||
"JobModifyIndex": 18,
|
||||
"JobStopped": false,
|
||||
"TaskGroups": {
|
||||
"cache": {
|
||||
"Desired": 1,
|
||||
"Events": null,
|
||||
"Healthy": 1,
|
||||
"Placed": 1,
|
||||
"Running": 0,
|
||||
"Unhealthy": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
## Scale Task Group <sup>beta 0.11</sup>
|
||||
|
||||
This endpoint performs a scaling action against a job.
|
||||
Currently, this endpoint supports scaling the count for a task group.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ----------------------- | ------------------ |
|
||||
| `POST` | `/v1/job/:job_id/scale` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api#blocking-queries) and
|
||||
[required ACLs](/api#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| `NO` | `namespace:scale-job` or `namespace:submit-job`<br />`namespace:sentinel-override` if `PolicyOverride` set |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
|
||||
the job file during submission). This is specified as part of the path.
|
||||
|
||||
- `Count` `(int: <optional>)` - Specifies the new task group count.
|
||||
|
||||
- `Target` `(json: required)` - JSON map containing the target of the scaling operation.
|
||||
Must contain a field `Group ` with the name of the task group that is the target of this scaling action.
|
||||
|
||||
- `Reason` `(string: <optional>)` - Description of the scale action, persisted as part of the scaling event.
|
||||
Indicates information or reason for scaling; one of `Reason` or `Error` must be provided.
|
||||
|
||||
- `Error` `(string: <optional>)` - Description of the scale action, persisted as part of the scaling event.
|
||||
Indicates an error state preventing scaling; one of `Reason` or `Error` must be provided.
|
||||
|
||||
- `Meta` `(json: <optional>)` - JSON blog that is persisted as part of the scaling event.
|
||||
|
||||
- `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
|
||||
will be overridden. This allows a job to be scaled when it would be denied
|
||||
by policy.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```javascript
|
||||
{
|
||||
"Count": 5,
|
||||
"Meta": {
|
||||
"metrics": [
|
||||
"cpu",
|
||||
"memory"
|
||||
]
|
||||
},
|
||||
"Reason": "metric did not satisfy SLA",
|
||||
"Target": {
|
||||
"Group": "cache"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://localhost:4646/v1/job/example/scale
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
This is the same payload as returned by job update.
|
||||
`EvalCreateIndex` and `EvalID` will only be present if the scaling operation resulted in the creation of an evaluation.
|
||||
|
||||
```json
|
||||
{
|
||||
"EvalCreateIndex": 45,
|
||||
"EvalID": "116f3ede-f6a5-f6e7-2d0e-1fda136390f0",
|
||||
"Index": 45,
|
||||
"JobModifyIndex": 44,
|
||||
"KnownLeader": false,
|
||||
"LastContact": 0,
|
||||
"Warnings": ""
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
104
website/pages/api-docs/scaling-policies.mdx
Normal file
104
website/pages/api-docs/scaling-policies.mdx
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: Scaling Policies - HTTP API
|
||||
sidebar_title: Scaling Policies <sup>Beta</sup>
|
||||
description: The /scaling/policy endpoints are used to list and view scaling policies.
|
||||
---
|
||||
|
||||
# Scaling Policies HTTP API
|
||||
|
||||
The `/scaling/policies` and `/scaling/policy/` endpoints are used to list and view scaling policies.
|
||||
|
||||
## List Scaling Policies
|
||||
|
||||
This endpoint returns the scaling policies from all jobs.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/scaling/policies` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api#blocking-queries), [consistency modes](/api#consistency-modes) and
|
||||
[required ACLs](/api#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ---------------------------------- |
|
||||
| `YES` | `all` | `namespace:list-scaling-policies` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell
|
||||
$ curl \
|
||||
https://localhost:4646/v1/scaling/policies
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"CreateIndex": 10,
|
||||
"Enabled": true,
|
||||
"ID": "5e9f9ef2-5223-6d35-bac1-be0f3cb974ad",
|
||||
"ModifyIndex": 10,
|
||||
"Target": {
|
||||
"Group": "cache",
|
||||
"Job": "example",
|
||||
"Namespace": "default"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Read Policy
|
||||
|
||||
This endpoint reads a specific scaling policy.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | ------------------ |
|
||||
| `GET` | `/scaling/policy/:policy_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api#blocking-queries), [consistency modes](/api#consistency-modes) and
|
||||
[required ACLs](/api#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | -------------------------------- |
|
||||
| `YES` | `all` | `namespace:read-scaling-policy` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `:policy_id` `(string: <required>)` - Specifies the ID of the scaling policy (as returned
|
||||
by the scaling policy list endpoint). This is specified as part of the path.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell
|
||||
$ curl \
|
||||
https://localhost:4646/v1/scaling/policy/5e9f9ef2-5223-6d35-bac1-be0f3cb974ad
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"CreateIndex": 10,
|
||||
"Enabled": true,
|
||||
"ID": "5e9f9ef2-5223-6d35-bac1-be0f3cb974ad",
|
||||
"Max": 10,
|
||||
"Min": 0,
|
||||
"ModifyIndex": 10,
|
||||
"Policy": {
|
||||
"engage": true,
|
||||
"foo": "bar",
|
||||
"howdy": "doody",
|
||||
"value": 6.0
|
||||
},
|
||||
"Target": {
|
||||
"Group": "cache",
|
||||
"Job": "example",
|
||||
"Namespace": "default"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user