github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/nia/api/tasks.mdx

405 lines
21 KiB
Markdown
Raw Blame History

---
layout: docs
page_title: Consul-Terraform-Sync Tasks API
description: >-
Consul-Terraform-Sync Tasks API
---
# Tasks
The `/tasks` endpoints interact with the tasks that Consul-Terraform-Sync (CTS) is responsible for running.
If you [run CTS with high availability enabled](/consul/docs/nia/usage/run-ha), you can send requests to the `/tasks` endpoint on CTS leader or follower instances. Requests to a follower instance, however, return a 400 Bad Request and error message. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/consul/docs/nia/usage/errors-ref) for more information.
## Get Tasks
This endpoint returns information about all existing tasks.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `GET` | `/tasks` | `application/json` |
### Response Statuses
| Status | Reason |
| ------ | ---------------------------------------------------- |
| 200 | Successfully retrieved and returned a list of tasks |
### Response Fields
| Name | Type | Description |
| ------------ | ------------- | ---------------------------------------------------------------------------------- |
| `request_id` | string | The ID of the request. Used for auditing and debugging purposes. |
| `tasks` | list[[Task](/consul/docs/nia/api/tasks#task-object)] | A list of Tasks |
### Example: Retrieve all tasks
In this example, CTS contains a single task
Request:
```shell-session
$ curl --request GET \
localhost:8558/v1/tasks
```
Response:
```json
{
"request_id": "0e0290f9-94df-3a4a-fd17-72467a16083c",
"tasks": [
{
"buffer_period": {
"enabled": true,
"max": "25s",
"min": "5s"
},
"condition": {
"services": {
"cts_user_defined_meta": {},
"datacenter": "",
"filter": "",
"names": ["api", "web"],
"namespace": "",
"use_as_module_input": true
}
},
"description": "Writes the service name, id, and IP address to a file",
"enabled": true,
"module": "path/to/module",
"module_input": {},
"name": "task_a",
"providers": ["my-provider"],
"variables": {},
"version": ""
}
]
}
```
## Get Task
This endpoint returns information about an existing task.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `GET` | `/tasks/:task_name` | `application/json` |
### Request Parameters
| Name | Required | Type | Description | Default |
| ------------ | -------- | ------ | ------------------------------------------ | ------- |
| `:task_name` | Required | string | Specifies the name of the task to retrieve | none |
### Response Statuses
| Status | Reason |
| ------ | ---------------------------------------------------- |
| 200 | Successfully retrieved and returned task information |
| 404 | Task with the given name not found |
### Response Fields
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------------- |
| `request_id` | string | The ID of the request. Used for auditing and debugging purposes. |
| `task` | object | The task's configuration information. See [task object](#task-object) for details. |
### Example: Retrieve a task
Request:
```shell-session
$ curl --request GET \
localhost:8558/v1/tasks/task_a
```
Response:
```json
{
"request_id": "b7559ab0-5111-381b-367a-0dfb7e216d41",
"task": {
"buffer_period": {
"enabled": true,
"max": "20s",
"min": "5s"
},
"condition": {
"consul_kv": {
"datacenter": "",
"namespace": "",
"path": "my_key",
"recurse": false,
"use_as_module_input": true
}
},
"description": "task triggering on consul-kv",
"enabled": true,
"module": "path/to/module",
"module_input": {
"services": {
"cts_user_defined_meta": {},
"datacenter": "",
"filter": "",
"names": ["api"],
"namespace": ""
}
},
"name": "task_a",
"providers": [],
"variables": {},
"version": ""
}
}
```
# Create Task
This endpoint allows for creation of a task. It only supports creation of a new task, and does not support updating a task.
| Method | Path | Produces |
| ------ | -------- | ------------------ |
| `POST` | `/tasks` | `application/json` |
### Request Parameters
| Name | Required | Type | Description | Default |
| ----- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `run` | Optional | string | Values can only be `"inspect"` and `"now"`.<br/><ul><li>`"inspect"`: Does not create the task but returns information on if/how resources would be changed for the proposed task creation.</li><li> `"now"`: Creates the task accordingly and immediately runs the task, rather than allowing the task to run at the natural daemon cadence</li></ul> | none |
### Request Body
| Name | Required | Type | Description |
| ------ | -------- | ------ | ---------------------------------------------------------------------------------- |
| `task` | Required | object | The task's configuration information. See [task object](#task-object) for details. |
### Response Statuses
| Status | Reason |
| ------ | ----------------------------- |
| 201 | Successfully created the task |
### Response Fields
| Name | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `request_id` | string | The ID of the request. Used for auditing and debugging purposes. |
| `task` | object | The task's configuration information after creation. See [task object](#task-object) for details. |
### Example: Create a task
Payload:
```json
{
"task": {
"description": "Writes the service name, id, and IP address to a file",
"enabled": true,
"name": "task_a",
"providers": ["my-provider"],
"condition": {
"services": {
"names": ["web", "api"]
}
},
"module": "path/to/module"
}
}
```
Request:
```shell-session
$ curl --header "Content-Type: application/json" \
--request POST \
--data @payload.json \
localhost:8558/v1/tasks
```
Response:
```json
{
"request_id": "0428ed18-1359-874c-8b27-742e43ebd7e7",
"task": {
"buffer_period": {
"enabled": true,
"max": "25s",
"min": "5s"
},
"condition": {
"services": {
"cts_user_defined_meta": {},
"datacenter": "",
"filter": "",
"names": ["api", "web"],
"namespace": "",
"use_as_module_input": true
}
},
"description": "Writes the service name, id, and IP address to a file",
"enabled": true,
"module": "path/to/module",
"module_input": {},
"name": "task_a",
"providers": ["my-provider"],
"variables": {},
"version": ""
}
}
```
## Update Task
This endpoint allows patch updates to specifically supported fields for existing tasks. Currently only supports updating a task's [`enabled` value](/consul/docs/nia/configuration#enabled-7).
| Method | Path | Produces |
| ------- | ------------------- | ------------------ |
| `PATCH` | `/tasks/:task_name` | `application/json` |
### Request Parameters
| Name | Required | Type | Description | Default |
| ------------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `:task_name` | Required | string | Specifies the name of the task to update | none |
| `run` | Optional | string | Values can only be `"inspect"` and `"now"`.<br/><ul><li>`"inspect"`: Does not update the task but returns information on if/how resources would be changed for the proposed task update.</li><li> `"now"`: Updates the task accordingly and immediately runs the task, rather than allowing the task to run at the natural daemon cadence</li></ul> | none |
### Request Body
| Name | Required | Type | Description |
| --------- | -------- | ------- | -------------------------------------------------------- |
| `enabled` | Required | boolean | Whether the task is enabled to run and manage resources. |
### Response Statuses
| Status | Reason |
| ------ | ---------------------------------- |
| 200 | Successfully updated the task |
| 404 | Task with the given name not found |
### Response Fields
| Name | Type | Description |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inspect` | object | Information on how resources would be changed given a proposed task update, similar to [inspect-mode](/consul/docs/nia/cli/#inspect-mode). This is only returned when passed the `run=inspect` request parameter. |
| `inspect.changes_present` | boolean | Whether or not changes were detected for running the proposed task update. |
| `inspect.plan` | string | The Terraform plan generated for the proposed task update. Note: a non-empty string does not necessarily indicate changes were detected. |
### Example: Disable a task
Request:
```shell-session
$ curl --header "Content-Type: application/json" \
--request PATCH \
--data '{"enabled":false}' \
localhost:8558/v1/tasks/task_a
```
Response:
```json
{}
```
### Example: Inspect enabling a task
Request:
```shell-session
$ curl --header "Content-Type: application/json" \
--request PATCH \
--data '{"enabled":true}' \
localhost:8558/v1/tasks/task_a?run=inspect
```
Response if no changes present:
```json
{
"inspect": {
"changes_present": false,
"plan": "No changes. Infrastructure is up-to-date. <truncated>"
}
}
```
Response if changes present:
```json
{
"inspect": {
"changes_present": true,
"plan": "<terraform plan truncated> Plan: 3 to add, 0 to change, 0 to destroy."
}
}
```
## Delete Task
This endpoint allows for deletion of existing tasks. It marks a task for deletion based on the name provided. If the task is not running, it will be deleted immediately. Otherwise, it will be deleted once the task is completed.
-> **Note:** Deleting a task will not destroy the infrastructure managed by the task.
| Method | Path | Produces |
| -------- | ------------------- | ------------------ |
| `DELETE` | `/tasks/:task_name` | `application/json` |
### Request Parameters
| Name | Required | Type | Description | Default |
| ------------ | -------- | ------ | ------------------------------------------ | ------- |
| `:task_name` | Required | string | Specifies the name of the task to retrieve | none |
### Response Statuses
| Status | Reason |
| ------ | ----------------------------------------- |
| 202 | Successfully marked the task for deletion |
| 404 | Task with the given name not found |
### Response Fields
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------- |
| `request_id` | string | The ID of the request. Used for auditing and debugging purposes. |
### Sample Request
```shell-session
$ curl --request DELETE \
localhost:8558/v1/tasks/task_a
```
### Sample Response
```json
{
"request_id": "9b23eea7-a435-2797-c71e-10c15766cd73"
}
```
## Task Object
The task object is used by the Task APIs as part of a request or response. It represents the task's [configuration information](/consul/docs/nia/configuration#task).
| Name | Required | Type | Description | Default |
| ----------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `buffer_period` | object | Optional | The buffer period for triggering task execution. | The global buffer period configured for CTS. |
| `buffer_period.enabled` | bool | Optional | Whether the buffer period is enabled or disabled. | The global buffer period's enabled value configured for CTS. |
| `buffer_period.min` | string | Optional | The minimum period of time to wait after changes are detected before triggering the task. | The global buffer period's min value configured for CTS. |
| `buffer_period.max` | string | Optional | The maximum period of time to wait after changes are detected before triggering the task. | The global buffer period's max value configured for CTS. |
| `condition` | object | Required | The [condition](/consul/docs/nia/configuration#task-condition) on which to trigger the task to execute. <br/><br/> If the task has the deprecated `services` field configured as a module input, it is represented here as `condition.services`. | none |
| `description` | string | Optional | The human readable text to describe the task. | none |
| `enabled` | bool | Optional | Whether the task is enabled or disabled from executing. | `true` |
| `module` | string | Required | The location of the Terraform module. | none |
| `module_input` | object | Optional | The additional [module input(s)](/consul/docs/nia/configuration#task-source-input) that the tasks provides to the Terraform module on execution. <br/><br/> If the task has the deprecated `services` field configured as a module input, it is represented here as `module_input.services`. | none |
| `name` | string | Required | The unique name of the task. | none |
| `providers` | list[string] | Optional | The list of provider names that the task's module uses. | none |
| `variables` | map[string] | Optional | The map of variables that are provided to the task's module. | none |
| `version` | string | Optional | The version of the configured module that the task uses. | The latest version. |
| `terraform_version` | string | Optional | <EnterpriseAlert inline /> **Deprecated in CTS 0.6.0 and will be removed in 0.8.0. Review `terraform_version` in `terraform_cloud_workspace` instead.** The version of Terraform to use for the HCP Terraform workspace associated with the task. This is only available when used with the [HCP Terraform driver](/consul/docs/nia/configuration#hcp-terraform-driver). | The latest compatible version supported by the organization. |
| `terraform_cloud_workspace` | object | Optional | <EnterpriseAlert inline /> The [configurable attributes of the HCP Terraform workspace](/consul/docs/nia/configuration#terraform_cloud_workspace) associated with the task. This option is only available when used with the [HCP Terraform driver](/consul/docs/nia/configuration#hcp-terraform-driver).| none |
Reference in New Issue View Git Blame Copy Permalink