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.

Request parameters

No request parameters are available for this endpoint.

Response statuses

• 200: Successfully retrieved the status.

Response fields

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.

Request parameters

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.

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.

Examples

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

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

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"
        }
      }
    ]
  }
}

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.

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.

Member objects

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

Example

The following command calls the /status/cluster endpoint:

$ 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:

{
  "cluster_name": "cluster-a",
  "members": [
    {
      "address": "cts-02.example.com",
      "healthy": true,
      "id": "cts-02",
      "leader": true,
      "service_name": "consul-terraform-sync"
    },
    {
      "healthy": true,
      "id": "cts-03",
      "leader": false,
      "service_name": "consul-terraform-sync"
    },
    {
      "healthy": true,
      "id": "cts-01",
      "leader": false,
      "service_name": "consul-terraform-sync"
    }
  ],
  "request_id": "e1bc2236-3d0e-5f5e-dc51-164a1cf6da88"
}