Status

The /status endpoints share status-related information for tasks. This information is available for understanding the status of individual tasks and across tasks.

The health status value is determined by aggregating the success or failure of the event of a task detecting changes in Consul services and then updating network infrastructure. Currently, only the 5 most recent events are stored in Consul-Terraform-Sync (CTS). For more information on the hierarchy of status information and how it is collected, see Status Information.

Overall Status

This endpoint currently returns the overall status information for all tasks.

Method	Path	Produces
`GET`	`/status`	`application/json`

Request Parameters

Currently no request parameters are offered for the overall status API.

Response Statuses

Status	Reason
200	Successfully retrieved the status

Response Fields

Name	Type	Description
`status`	object	The summary count of how many tasks have a given health status value
`status.successful`	integer	The number of tasks that have a `successful` health status.
`status.errored`	integer	The number of tasks that have an `errored` health status.
`status.critical`	integer	The number of tasks that have a `critical` health status.
`status.unknown`	integer	The number of tasks that have an `unknown` health status.
`enabled`	object	The summary count of how many tasks are enabled or disabled.
`enabled.true`	integer	The number of tasks that are enabled.
`enabled.false`	integer	The number of tasks that are disabled.

Example

Request:

$ curl localhost:8558/v1/status

Response:

{
  "task_summary": {
    "status": {
      "successful": 28,
      "errored": 5,
      "critical": 1,
      "unknown": 0
    },
    "enabled": {
      "true": 32,
      "false": 2
    }
  }
}

Task Status

This endpoint returns the individual task status information for a single specified task or for all tasks.

Task health status value is determined by the success or failure of all stored event data on the process of updating network infrastructure for a task. Currently only the 5 most recent events are stored per task.

Successful: The most recent stored event is successful.
Errored: The most recent stored event is not successful but all previous stored events are successful.
Critical: The most recent stored event is not successful and one or more previous stored events are also not successful.
Unknown: No event data is stored for the task.

Method	Path	Produces
`GET`	`/status/tasks/:task_name`	`application/json`

Request Parameters

Name	Required	Type	Description	Default
`:task_name`	Optional	string	Option to specify the name of the task to return in the response. If not specified, all tasks are returned in the response.	none
`include`	Optional	string	Only accepts the value `“events”`. Use to include stored event information in response.	none
`status`	Optional	string	Only accepts health status values `“successful”`, `“errored”`, `“critical”`, or `“unknown”`. Use to filter response by tasks that have the specified health status value. Recommend setting this parameter when requesting all tasks i.e. no `task` parameter is set.	none

Response Statuses

Status	Reason
200	Successfully retrieved the task status
404	Task with the given name not found

Response Fields

The response is a JSON map of task name to a status information structure with the following fields.

Name	Type	Description
`task_name`	string	Name of the task as configured in CTS.
`status`	string	Values are `“successful”`, `“errored”`, `“critical”`, or `“unknown”`. This is determined by the success or failure of all stored events on the network infrastructure update process for the task, as described earlier.
`enabled`	boolean	Whether the task is enabled or not.
`services`	list[string]	Deprecated in CTS 0.5.0 and will be removed in a future major release. List of the services configured for the task.
`providers`	list[string]	Deprecated in CTS 0.5.0 and will be removed in v0.8.0. List of the providers configured for the task.
`events_url`	string	Relative URL to retrieve the event data stored for the task.
`events`	list[Event]	List of stored events that inform the task’s status. See section below for information on event data. This field is only included in the response upon request by setting the `?include=events` parameter. The relative URL for the request to include events can be retrieved from the `events_url` field.

Event

Event represents the process of updating network infrastructure of a task. The data is captured in a JSON structure. For more details on the scope of an event, see Event.

Name	Type	Description
`id`	string	UUID to uniquely identify the event.
`success`	boolean	Indication of whether the event was successful or not.
`start_time`	time	Time when the event started.
`end_time`	time	Time when the event ended.
`task_name`	string	Name that task is configured with in CTS.
`error`	object	Information when the event fails. Null when successful.
`error.message`	string	Error message that is returned on failure.
`config`	object	Deprecated in CTS 0.5.0 and will be removed in v0.8.0. Configuration values for the task when it was run.
`config.services`	list[string]	Deprecated in CTS 0.5.0 and will be removed in v0.8.0. List of the services configured for the task.
`config.source`	string	Deprecated in CTS 0.5.0 and will be removed in v0.8.0. Module configured for the task.
`config.providers`	list[string]	Deprecated in CTS 0.5.0 and will be removed in v0.8.0. List of the providers configured for the task.

Example: All Task Statuses

Request:

$ curl localhost:8558/v1/status/tasks

Response:

{
  "task_a": {
    "task_name": "task_a",
    "status": "successful",
    "enabled": true,
    "providers": [
      "local"
    ],
    "services": [
      "api"
    ],
    "events_url": "/v1/status/tasks/task_a?include=events"
  },
  "task_b": {
    "task_name": "task_b",
    "status": "errored",
    "enabled": false,
    "providers": [
      "null"
    ],
    "services": [
      "web"
    ],
    "events_url": "/v1/status/tasks/task_b?include=events"
  }
}

Example: Individual Task Status with Events

Request:

$ curl localhost:8558/v1/status/tasks/task_b?include=events

Response:

{
  "task_b": {
    "task_name": "task_b",
    "status": "errored",
    "enabled": false,
    "providers": [
      "null"
    ],
    "services": [
      "web",
    ],
    "events_url": "/v1/status/tasks/task_b?include=events",
    "events": [
      {
        "id": "44137ba2-8fc9-6cbe-0e0e-e9305ee4f7f9",
        "success": false,
        "start_time": "2020-11-24T12:06:51.858292-05:00",
        "end_time": "2020-11-24T12:06:52.770165-05:00",
        "task_name": "task_b",
        "error": {
          "message": "example error: terraform-apply error"
        },
        "config": {
          "providers": [
            "null"
          ],
          "services": [
            "web"
          ],
          "module": "../modules/test_task"
        }
      },
      {
        "id": "ef202675-502f-431f-b133-ed64d15b0e0e",
        "success": true,
        "start_time": "2020-11-24T12:04:18.651231-05:00",
        "end_time": "2020-11-24T12:04:20.900115-05:00",
        "task_name": "task_b",
        "error": null,
        "config": {
          "providers": [
            "null"
          ],
          "services": [
            "web",
          ],
          "module": "../modules/test_task"
        }
      }
    ]
  }
}