Merge pull request #7478 from hashicorp/docs-scaling-api
docs: nomad scaling policy api
This commit is contained in:
Mahmood Ali
GitHub
commit
28b951be81
|
|
@ -24,6 +24,7 @@ export default [
|
|||
'plugins',
|
||||
'quotas',
|
||||
'regions',
|
||||
'scaling-policies',
|
||||
'search',
|
||||
'sentinel-policies',
|
||||
'status',
|
||||
|
|
|
|||
|
|
@ -146,6 +146,7 @@ export default [
|
|||
'reschedule',
|
||||
'resources',
|
||||
'restart',
|
||||
'scaling',
|
||||
'service',
|
||||
'sidecar_service',
|
||||
'sidecar_task',
|
||||
|
|
|
|||
|
|
@ -1726,3 +1726,134 @@ $ curl \
|
|||
"JobModifyIndex": 34
|
||||
}
|
||||
```
|
||||
|
||||
## Read Job Scale Status <sup>0.11 Beta</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>0.11 Beta</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 block 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>0.11 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 <sup>0.11 Beta</sup>
|
||||
|
||||
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 Scaling Policy <sup>0.11 Beta</sup>
|
||||
|
||||
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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
54
website/pages/docs/job-specification/scaling.mdx
Normal file
54
website/pages/docs/job-specification/scaling.mdx
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: scaling Stanza - Job Specification
|
||||
sidebar_title: scaling <sup>0.11 Beta</sup>
|
||||
description: The "scaling" stanza allows specifying scaling policy for a task group
|
||||
---
|
||||
|
||||
# `scaling` Stanza
|
||||
|
||||
<Placement groups={['job', 'group']} />
|
||||
|
||||
The `scaling` stanza allows configuring scaling options for a task group, for the purpose
|
||||
of supporting external autoscalers like the [Nomad Autoscaler](https://github.com/hashicorp/nomad-autoscaler).
|
||||
|
||||
```hcl
|
||||
job "example" {
|
||||
datacenters = ["dc1"]
|
||||
group "cache" {
|
||||
task "redis" {
|
||||
driver = "docker"
|
||||
config {
|
||||
image = "redis:3.2"
|
||||
}
|
||||
}
|
||||
scaling {
|
||||
enabled = true
|
||||
min = 0
|
||||
max = 10
|
||||
policy {
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `scaling` Parameters
|
||||
|
||||
- `min` - <code>(int: nil)</code> - The minimum acceptible count for the task group.
|
||||
This should be honored by the external autoscaler. It will also be honored by Nomad
|
||||
during job updates and scaling operations. Defaults to the specified task group [count][].
|
||||
|
||||
- `max` - <code>(int: <required>)</code> - The maximum acceptible count for the task group.
|
||||
This should be honored by the external autoscaler. It will also be honored by Nomad
|
||||
during job updates and scaling operations.
|
||||
|
||||
- `enabled` - <code>(bool: false)</code> - Whether the scaling policy is enabled.
|
||||
This is intended to allow temporarily disabling an autoscaling policy, and should be
|
||||
honored by the external autoscaler.
|
||||
|
||||
- `policy` - <code>(map<string|...>: nil)</code> - The autoscaling policy. This is
|
||||
opaque to Nomad, consumed and parsed only by the external autoscaler. Therefore,
|
||||
its contents are specific to the autoscaler; see autoscaler documentation.
|
||||
|
||||
[count]: /docs/job-specification/group/#inlinecode-count-10 'Nomad Task Group specification'
|
||||
Loading…
Reference in a new issue