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

MethodPathProduces
GET/statusapplication/json

Request Parameters

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

Response Fields

  • task_summary - Summary of task information. See Task Status API to learn more about how health status is determined.
    • status - Summary count of how many tasks have each health status value
      • successful - (int) The number of tasks that have a ‘successful’ health status
      • errored - (int) The number of tasks that have a ‘errored’ health status
      • critical - (int) The number of tasks that have a ‘critical’ health status
      • unknown - (int) The number of tasks that have an ‘unknown’ health status
    • enabled - Summary count of how many tasks are enabled or disabled
      • true - (int) The number of tasks that are enabled
      • false - (int) The number of tasks that are disabled

Example

Request:

  1. $ curl localhost:8558/v1/status

Response:

  1. {
  2.   "task_summary": {
  3.     "status": {
  4.       "successful": 28,
  5.       "errored": 5,
  6.       "critical": 1,
  7.       "unknown": 0
  8.     },
  9.     "enabled": {
  10.       "true": 32,
  11.       "false": 2
  12.     }
  13.   }
  14. }

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.
MethodPathProduces
GET/status/tasks/:taskapplication/json

Request Parameters

  • task - (string) Option to specify the name of the task to return in the response. If not specified, all tasks are returned in the response.
  • include - (string) Only accepts the value “events”. Use to include stored event information in response.
  • status - (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.

Response Fields

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

  • task_name - (string) Name that task is configured with in Consul-Terraform-Sync.
  • 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 - (bool) Whether the task is enabled or not.
  • services - (list[string]) List of the services configured for the task.
  • providers - (list[string]) 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.

  • id - (string) UUID to uniquely identify the event.
  • success - (bool) 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 Consul-Terraform-Sync.
  • error Information when the event fails. Null when successful.
    • message - (string) Error message that is returned on failure.
  • config
    • services - (list[string]) List of the services configured for the task.
    • source - (string) Source configured for the task.
    • providers - (list[string]) List of the providers configured for the task.

Example: All Task Statuses

Request:

  1. $ curl localhost:8558/v1/status/tasks

Response:

  1. {
  2.   "task_a": {
  3.     "task_name": "task_a",
  4.     "status": "successful",
  5.     "enabled": true,
  6.     "providers": [
  7.       "local"
  8.     ],
  9.     "services": [
  10.       "api"
  11.     ],
  12.     "events_url": "/v1/status/tasks/task_a?include=events"
  13.   },
  14.   "task_b": {
  15.     "task_name": "task_b",
  16.     "status": "errored",
  17.     "enabled": false,
  18.     "providers": [
  19.       "null"
  20.     ],
  21.     "services": [
  22.       "web"
  23.     ],
  24.     "events_url": "/v1/status/tasks/task_b?include=events"
  25.   }
  26. }

Example: Individual Task Status with Events

Request:

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

Response:

  1. {
  2.   "task_b": {
  3.     "task_name": "task_b",
  4.     "status": "errored",
  5.     "enabled": false,
  6.     "providers": [
  7.       "null"
  8.     ],
  9.     "services": [
  10.       "web",
  11.     ],
  12.     "events_url": "/v1/status/tasks/task_b?include=events",
  13.     "events": [
  14.       {
  15.         "id": "44137ba2-8fc9-6cbe-0e0e-e9305ee4f7f9",
  16.         "success": false,
  17.         "start_time": "2020-11-24T12:06:51.858292-05:00",
  18.         "end_time": "2020-11-24T12:06:52.770165-05:00",
  19.         "task_name": "task_b",
  20.         "error": {
  21.           "message": "example error: terraform-apply error"
  22.         },
  23.         "config": {
  24.           "providers": [
  25.             "null"
  26.           ],
  27.           "services": [
  28.             "web",
  29.           ],
  30.           "source": "../modules/test_task"
  31.         }
  32.       },
  33.       {
  34.         "id": "ef202675-502f-431f-b133-ed64d15b0e0e",
  35.         "success": true,
  36.         "start_time": "2020-11-24T12:04:18.651231-05:00",
  37.         "end_time": "2020-11-24T12:04:20.900115-05:00",
  38.         "task_name": "task_b",
  39.         "error": null,
  40.         "config": {
  41.           "providers": [
  42.             "null"
  43.           ],
  44.           "services": [
  45.             "web",
  46.           ],
  47.           "source": "../modules/test_task"
  48.         }
  49.       }
  50.     ]
  51.   }
  52. }