Status

The /status endpoints return status-related information for tasks. This endpoint returns a count of successful and failed task events that are recorded whenever tasks execute an automation. Currently, only the five most recent events are stored in Consul-Terraform-Sync (CTS). For more information on the hierarchy of status information and how it is collected, refer to Status Information.

If CTS is configured for high availability, you can send requests to the /status/cluster endpoint path on any CTS cluster member instance to receive information about the entire cluster. Calling the status endpoint path (without /cluster), however, returns a 400 error if the request is sent to a follower instance. The error message depends on what information the follower instance is able to obtain about the leader. Refer to Error Messages for more information.

Status for all tasks

This endpoint returns the overall status information for all tasks.

MethodPathProduces
GET/statusapplication/json

Request parameters

No request parameters are available for this endpoint.

Response statuses

  • 200: Successfully retrieved the status.

Response fields

NameTypeDescription
statusobjectThe summary count of how many tasks have a given health status value
status.successfulintegerThe number of tasks that have a successful health status.
status.erroredintegerThe number of tasks that have an errored health status.
status.criticalintegerThe number of tasks that have a critical health status.
status.unknownintegerThe number of tasks that have an unknown health status.
enabledobjectThe summary count of how many tasks are enabled or disabled.
enabled.trueintegerThe number of tasks that are enabled.
enabled.falseintegerThe 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/:task_nameapplication/json

Request parameters

NameRequiredTypeDescriptionDefault
:task_nameOptionalstringOption to specify the name of the task to return in the response. If not specified, all tasks are returned in the response.none
includeOptionalstringOnly accepts the value “events”. Use to include stored event information in response.none
statusOptionalstringOnly 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

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

NameTypeDescription
task_namestringName of the task as configured in CTS.
statusstringValues 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.
enabledbooleanWhether the task is enabled or not.
serviceslist[string]Deprecated in CTS 0.5.0 and will be removed in a future major release. List of the services configured for the task.
providerslist[string]Deprecated in CTS 0.5.0 and will be removed in v0.8.0. List of the providers configured for the task.
events_urlstringRelative URL to retrieve the event data stored for the task.
eventslist[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.

NameTypeDescription
idstringUUID to uniquely identify the event.
successbooleanIndication of whether the event was successful or not.
start_timetimeTime when the event started.
end_timetimeTime when the event ended.
task_namestringName that task is configured with in CTS.
errorobjectInformation when the event fails. Null when successful.
error.messagestringError message that is returned on failure.
configobjectDeprecated in CTS 0.5.0 and will be removed in v0.8.0. Configuration values for the task when it was run.
config.serviceslist[string]Deprecated in CTS 0.5.0 and will be removed in v0.8.0. List of the services configured for the task.
config.sourcestringDeprecated in CTS 0.5.0 and will be removed in v0.8.0. Module configured for the task.
config.providerslist[string]Deprecated in CTS 0.5.0 and will be removed in v0.8.0. List of the providers configured for the task.

Examples

The following examples call status endpoints to retrieve information about tasks.

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

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. "module": "../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. "module": "../modules/test_task"
  48. }
  49. }
  50. ]
  51. }
  52. }

Cluster status

The /v1/status/cluster API endpoint returns information about high-availability clusters and its members, such as health status and leadership. This endpoint is only supported when using CTS in high availability mode. If you call the endpoint without configuring CTS for high availability, then CTS prints an error to the console. Refer to Error Messages for information about CTS error messages.

MethodPathResponse format
GET/status/clusterapplication/json

Request parameters

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

Request statuses

  • 200: Successfully retrieved the cluster status

Response fields

The following table describes the responses that the status/cluster endpoint can send.

FieldTypeDescription
cluster_namestringIdentifies the name of the cluster.
memberslist[member]Contains a list of member objects. Each object in the members list represents a CTS instance.

Member objects

The following table describes the fields available for objects in the members array.

FieldTypeDescription
addressstringIndicates the location of the instance. The address is only included in the response if the high_availability.instance.address option is configured on the leader instance. Refer to the high availability instance configuration reference for additional information.
healthybooleanIndicates the health of the service instance health. Refer to Service Registration for additional information.
idstringIndicates the service registration ID. Refer to Service Registration for additional information.
leaderbooleanIdentifies the cluster leader.
service_namestringIdentifies the name of the service that the instance represents. The value is set by the service_name field in the Service Registration configuration.

Example

The following command calls the /status/cluster endpoint:

  1. $ curl request GET http://localhost:8553/v1/status/cluster

The following example response shows three CTS instances. The cluster leader is cts-02 and is advertising that its address is cts-02.example.com:

  1. {
  2. "cluster_name": "cluster-a",
  3. "members": [
  4. {
  5. "address": "cts-02.example.com",
  6. "healthy": true,
  7. "id": "cts-02",
  8. "leader": true,
  9. "service_name": "consul-terraform-sync"
  10. },
  11. {
  12. "healthy": true,
  13. "id": "cts-03",
  14. "leader": false,
  15. "service_name": "consul-terraform-sync"
  16. },
  17. {
  18. "healthy": true,
  19. "id": "cts-01",
  20. "leader": false,
  21. "service_name": "consul-terraform-sync"
  22. }
  23. ],
  24. "request_id": "e1bc2236-3d0e-5f5e-dc51-164a1cf6da88"
  25. }