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, 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 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]	A list of Tasks

Example: Retrieve all tasks

In this example, CTS contains a single task

Request:

$ curl --request GET \
  localhost:8558/v1/tasks

Response:

{
  "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 for details.

Example: Retrieve a task

Request:

$ curl --request GET \
  localhost:8558/v1/tasks/task_a

Response:

{
  "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"`. `"inspect"`: Does not create the task but returns information on if/how resources would be changed for the proposed task creation. `"now"`: Creates the task accordingly and immediately runs the task, rather than allowing the task to run at the natural daemon cadence	none

Request Body

Name	Required	Type	Description
`task`	Required	object	The task's configuration information. See 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 for details.

Example: Create a task

Payload:

{
  "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:

$ curl --header "Content-Type: application/json" \
  --request POST \
  --data @payload.json \
  localhost:8558/v1/tasks

Response:

{
  "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.

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"`. `"inspect"`: Does not update the task but returns information on if/how resources would be changed for the proposed task update. `"now"`: Updates the task accordingly and immediately runs the task, rather than allowing the task to run at the natural daemon cadence	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. 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:

$ curl --header "Content-Type: application/json" \
  --request PATCH \
  --data '{"enabled":false}' \
  localhost:8558/v1/tasks/task_a

Response:

{}

Example: Inspect enabling a task

Request:

$ curl --header "Content-Type: application/json" \
  --request PATCH \
  --data '{"enabled":true}' \
  localhost:8558/v1/tasks/task_a?run=inspect

Response if no changes present:

{
  "inspect": {
    "changes_present": false,
    "plan": "No changes. Infrastructure is up-to-date. <truncated>"
  }
}

Response if changes present:

{
  "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

$ curl --request DELETE \
  localhost:8558/v1/tasks/task_a

Sample Response

{
  "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.

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 on which to trigger the task to execute. 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) that the tasks provides to the Terraform module on execution. 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	Enterprise 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 Terraform Cloud workspace associated with the task. This is only available when used with the Terraform Cloud driver.	The latest compatible version supported by the organization.
`terraform_cloud_workspace`	object	Optional	Enterprise The configurable attributes of the Terraform Cloud workspace associated with the task. This option is only available when used with the Terraform Cloud driver.	none