diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js index be144e6cc..d20d62e04 100644 --- a/website/data/api-navigation.js +++ b/website/data/api-navigation.js @@ -24,6 +24,7 @@ export default [ 'plugins', 'quotas', 'regions', + 'scaling-policies', 'search', 'sentinel-policies', 'status', diff --git a/website/pages/api-docs/jobs.mdx b/website/pages/api-docs/jobs.mdx index 31a5b047c..f95697c8e 100644 --- a/website/pages/api-docs/jobs.mdx +++ b/website/pages/api-docs/jobs.mdx @@ -1726,3 +1726,135 @@ $ curl \ "JobModifyIndex": 34 } ``` + +## Read Job Scale Status beta 0.11 + +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: )` - 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 beta 0.11 + +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`
`namespace:sentinel-override` if `PolicyOverride` set | + +### Parameters + +- `:job_id` `(string: )` - Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +- `Count` `(int: )` - 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: )` - 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: )` - 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: )` - 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": "" +} +``` + diff --git a/website/pages/api-docs/scaling-policies.mdx b/website/pages/api-docs/scaling-policies.mdx new file mode 100644 index 000000000..03f68c05b --- /dev/null +++ b/website/pages/api-docs/scaling-policies.mdx @@ -0,0 +1,104 @@ +--- +layout: api +page_title: Scaling Policies - HTTP API +sidebar_title: Scaling Policies Beta +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: )` - 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" + } +} +``` +