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.

Response Statuses

Response Fields

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.

Request Parameters

Response Statuses

Response Fields

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.

Request Parameters

Request Body

Response Statuses

Response Fields

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.

Request Parameters

Request Body

Response Statuses

Response Fields

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.

Request Parameters

Response Statuses

Response Fields

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	EnterpriseEnterprise 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	EnterpriseEnterprise 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