From 89d86bc4bdf8fca563719b88e3e93bc27febda5e Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Thu, 29 Jun 2017 16:15:13 -0700 Subject: [PATCH] Deployments HTTP docs --- api/deployments.go | 1 + api/jobs.go | 1 + website/source/api/deployments.html.md | 480 ++++++++++++++++++ website/source/api/index.html.md | 4 +- website/source/api/jobs.html.md | 2 + .../docs/job-specification/group.html.md | 1 + website/source/layouts/api.erb | 4 + 7 files changed, 492 insertions(+), 1 deletion(-) create mode 100644 website/source/api/deployments.html.md diff --git a/api/deployments.go b/api/deployments.go index f8b6b879d..feeedad8a 100644 --- a/api/deployments.go +++ b/api/deployments.go @@ -106,6 +106,7 @@ func (d *Deployments) PromoteGroups(deploymentID string, groups []string, q *Wri return &resp, wm, nil } +// XXX // SetAllocHealth is used to set allocation health for allocs that are part of // the given deployment func (d *Deployments) SetAllocHealth(deploymentID string, healthy, unhealthy []string, q *WriteOptions) (*DeploymentUpdateResponse, *WriteMeta, error) { diff --git a/api/jobs.go b/api/jobs.go index 3766d6b52..889791485 100644 --- a/api/jobs.go +++ b/api/jobs.go @@ -224,6 +224,7 @@ func (j *Jobs) Dispatch(jobID string, meta map[string]string, return &resp, wm, nil } +// XXX // Revert is used to revert the given job to the passed version. If // enforceVersion is set, the job is only reverted if the current version is at // the passed version. diff --git a/website/source/api/deployments.html.md b/website/source/api/deployments.html.md new file mode 100644 index 000000000..8154efb60 --- /dev/null +++ b/website/source/api/deployments.html.md @@ -0,0 +1,480 @@ +--- +layout: api +page_title: Deployments - HTTP API +sidebar_current: api-deployments +description: |- + The /deployment are used to query for and interact with deployments. +--- + +# Deployments HTTP API + +The `/deployment` endpoints are used to query for and interact with deployments. + +## List Deployments + +This endpoint lists all deployments. + +| Method | Path | Produces | +| ------ | ------------------------ | -------------------------- | +| `GET` | `/v1/deployments` | `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 | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter deployments on based on + an index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/deployments +``` + +```text +$ curl \ + https://nomad.rocks/v1/deployments?prefix=25ba81c +``` + +### Sample Response + +```json +[ + { + "ID": "70638f62-5c19-193e-30d6-f9d6e689ab8e", + "JobID": "example", + "JobVersion": 1, + "JobModifyIndex": 17, + "JobCreateIndex": 7, + "TaskGroups": { + "cache": { + "Promoted": false, + "DesiredCanaries": 1, + "DesiredTotal": 3, + "PlacedAllocs": 1, + "HealthyAllocs": 0, + "UnhealthyAllocs": 0 + } + }, + "Status": "running", + "StatusDescription": "", + "CreateIndex": 19, + "ModifyIndex": 19 + } +] +``` + +## Read Deployment + +This endpoint reads information about a specific deployment by ID. + +| Method | Path | Produces | +| ------ | -------------------------------- | -------------------------- | +| `GET` | `/v1/deployment/:deployment_id` | `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 | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:deployment_id` `(string: )`- Specifies the UUID of the deployment. + This must be the full UUID, not the short 8-character one. This is specified + as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/deployment/70638f62-5c19-193e-30d6-f9d6e689ab8e +``` + +### Sample Response + +```json +{ + "ID": "70638f62-5c19-193e-30d6-f9d6e689ab8e", + "JobID": "example", + "JobVersion": 1, + "JobModifyIndex": 17, + "JobCreateIndex": 7, + "TaskGroups": { + "cache": { + "Promoted": false, + "DesiredCanaries": 1, + "DesiredTotal": 3, + "PlacedAllocs": 1, + "HealthyAllocs": 0, + "UnhealthyAllocs": 0 + } + }, + "Status": "running", + "StatusDescription": "", + "CreateIndex": 19, + "ModifyIndex": 19 +} +``` + +## List Allocations for Deployment + +This endpoint lists the allocations created or modified for the given +deployment. + +| Method | Path | Produces | +| ------ | ------------------------------------------- | -------------------------- | +| `GET` | `/v1/deployment/allocations/:deployment_id` | `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 | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:deployment_id` `(string: )`- Specifies the UUID of the deployment. + This must be the full UUID, not the short 8-character one. This is specified + as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/deployment/allocations/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +[ + { + "ID": "287b65cc-6c25-cea9-0332-e4a75ca2af98", + "EvalID": "9751cb74-1a0d-190e-d026-ad2bc666ad2c", + "Name": "example.cache[0]", + "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823", + "JobID": "example", + "TaskGroup": "cache", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "TaskStates": { + "redis": { + "State": "running", + "Failed": false, + "StartedAt": "2017-06-29T22:29:41.52000268Z", + "FinishedAt": "0001-01-01T00:00:00Z", + "Events": [ + { + "Type": "Received", + "Time": 1498775380693307400, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Task Setup", + "Time": 1498775380693659000, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "Building Task Directory", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Started", + "Time": 1498775381508493800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + } + ] + } + }, + "DeploymentStatus": null, + "CreateIndex": 19, + "ModifyIndex": 22, + "CreateTime": 1498775380678486300 + } +] +``` + +## Fail Deployment + +This endpoint is used to mark a deployment as failed. This should be done to +force the scheduler to stop creating allocations as part of the deployment or to +cause a rollback to a previous job version. + +| Method | Path | Produces | +| ------- | ------------------------------------ | -------------------------- | +| `POST` | `/v1/deployment/fail/:deployment_id` | `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` | `none` | + +### Parameters + +- `:deployment_id` `(string: )`- Specifies the UUID of the deployment. + This must be the full UUID, not the short 8-character one. This is specified + as part of the path. + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/deployment/fail/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +{ + "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", + "EvalCreateIndex": 20, + "DeploymentModifyIndex": 20, + "Index": 20 +} +``` + +## Pause Deployment + +This endpoint is used to pause or unpause a deployment. This is done to pause +a rolling upgrade or resume it. + +| Method | Path | Produces | +| ------- | ------------------------------------- | -------------------------- | +| `POST` | `/v1/deployment/pause/:deployment_id` | `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` | `none` | + +### Parameters + +- `:deployment_id` `(string: )`- Specifies the UUID of the deployment. + This must be the full UUID, not the short 8-character one. This is specified + as part of the path. + +- `Pause` `(bool: false)` - Specifies whether to pause or resume the deployment. + +### Sample Payload + +```javascript +{ + "Pause": true +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/deployment/pause/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +{ + "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", + "EvalCreateIndex": 20, + "DeploymentModifyIndex": 20, + "Index": 20 +} +``` + +## Promote Deployment + +This endpoint is used to promote task groups that have canaries for a +deployment. This should be done when the placed canaries are healthy and the +rolling upgrade of the remaining allocations should begin. + +| Method | Path | Produces | +| ------- | ------------------------------------- | -------------------------- | +| `POST` | `/v1/deployment/promote/:deployment_id` | `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` | `none` | + +### Parameters + +- `:deployment_id` `(string: )`- Specifies the UUID of the deployment. + This must be the full UUID, not the short 8-character one. This is specified + as part of the path. + +- `All` `(bool: false)` - Specifies whether all task groups should be promoted. + +- `Groups` `(array: nil)` - Specifies a particular set of task groups + that should be promoted. + +### Sample Payload + +```javascript +{ + "All": true +} +``` + +```javascript +{ + "Groups": ["web", "api-server"] +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/deployment/promote/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +{ + "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", + "EvalCreateIndex": 20, + "DeploymentModifyIndex": 20, + "Index": 20 +} +``` + +## Set Allocation Health in Deployment + +This endpoint is used to set the health of an allocation that is in the +deployment manually. In some use cases, automatic detection of allocation health +may not be desired. As such those task groups can be marked with an upgrade +policy that uses `health_check = "manual"`. Those allocations must have their +health marked manually using this endpoint. Marking an allocation as healthy +will allow the rolling upgrade to proceed. Marking it as failed will cause the +deployment to fail. + +| Method | Path | Produces | +| ------- | ------------------------------------------------- | -------------------------- | +| `POST` | `/v1/deployment/allocation-health/:deployment_id` | `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` | `none` | + +### Parameters + +- `:deployment_id` `(string: )`- Specifies the UUID of the deployment. + This must be the full UUID, not the short 8-character one. This is specified + as part of the path. + +- `HealthyAllocationIDs` `(array: nil)` - Specifies the set of + allocation that should be marked as healthy. + +- `UnhealthyAllocationIDs` `(array: nil)` - Specifies the set of + allocation that should be marked as unhealthy. + +### Sample Payload + +```javascript +{ + "HealthyAllocationIDs": [ + "eb13bc8a-7300-56f3-14c0-d4ad115ec3f5", + "6584dad8-7ae3-360f-3069-0b4309711cc1" + ] +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/deployment/allocation-health/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +{ + "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", + "EvalCreateIndex": 20, + "DeploymentModifyIndex": 20, + "Index": 20 +} +``` diff --git a/website/source/api/index.html.md b/website/source/api/index.html.md index c2e3fabd1..8b8fa4f08 100644 --- a/website/source/api/index.html.md +++ b/website/source/api/index.html.md @@ -52,6 +52,7 @@ There are four primary nouns in Nomad: - jobs - nodes - allocations +- deployments - evaluations [![Nomad Data Model](/assets/images/nomad-data-model.png)](/assets/images/nomad-data-model.png) @@ -62,7 +63,8 @@ require resources. Nodes are the servers in the clusters that tasks can be scheduled on. The mapping of tasks in a job to nodes is done using allocations. An allocation is used to declare that a set of tasks in a job should be run on a particular node. Scheduling is the process of determining the appropriate -allocations and is done as part of an evaluation. +allocations and is done as part of an evaluation. Deployments are objects to +track a rolling update of allocations between two versions of a job. The API is modeled closely on the underlying data model. Use the links to the left for documentation about specific endpoints. There are also "Agent" APIs diff --git a/website/source/api/jobs.html.md b/website/source/api/jobs.html.md index 7d4af5be5..317d2f082 100644 --- a/website/source/api/jobs.html.md +++ b/website/source/api/jobs.html.md @@ -887,6 +887,8 @@ The table below shows this endpoint's support for ```text $ curl \ + --request POST \ + --payload @payload.json \ https://nomad.rocks/v1/job/my-job/summary ``` diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md index d5b075e94..c202a8c29 100644 --- a/website/source/docs/job-specification/group.html.md +++ b/website/source/docs/job-specification/group.html.md @@ -113,3 +113,4 @@ group "example" { [ephemeraldisk]: /docs/job-specification/ephemeral_disk.html "Nomad ephemeral_disk Job Specification" [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" [restart]: /docs/job-specification/restart.html "Nomad restart Job Specification" +[vault]: /docs/job-specification/vault.html "Nomad vault Job Specification" diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 0cf29528f..cf0f9fbdd 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -27,6 +27,10 @@ Client + > + Deployments + + > Evaluations