mirror of https://github.com/hashicorp/consul
298 lines
11 KiB
Markdown
298 lines
11 KiB
Markdown
---
|
||
layout: docs
|
||
page_title: Consul-Terraform-Sync Status API
|
||
description: >-
|
||
Consul-Terraform-Sync Status API
|
||
---
|
||
# 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](/docs/nia/tasks#status-information).
|
||
|
||
If you [run CTS with high availability enabled](/docs/nia/usage/run-ha), you can send requests to the `/status` 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](/docs/nia/usage/errors-ref) for more information.
|
||
|
||
## Status for all tasks
|
||
|
||
This endpoint 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:
|
||
```shell-session
|
||
$ curl localhost:8558/v1/status
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"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](/docs/nia/tasks#event) 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](/docs/nia/api/status#event)] | List of stored events that inform the task's status. See [section below](/docs/nia/api/status#event) 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](/docs/nia/tasks#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.
|
||
|
||
### Examples
|
||
|
||
The following examples call `status` endpoints to retrieve information about tasks.
|
||
|
||
#### All task statuses
|
||
|
||
Request:
|
||
```shell-session
|
||
$ curl localhost:8558/v1/status/tasks
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"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:
|
||
```shell-session
|
||
$ curl localhost:8558/v1/status/tasks/task_b?include=events
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"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 the cluster and member instances, such as health status and leadership. This endpoint is only supported when using CTS in [high availability mode](/docs/usage/run-ha). If you call the endpoint without configuring CTS for high availability, then CTS prints an error to the console. Refer to [Error Messages](/docs/nia/usage/errors-ref) for information about CTS error messages.
|
||
|
||
| Method | Path | Response format |
|
||
| ------ | ----------------- | ------------------ |
|
||
| `GET` | `/status/cluster` | `application/json` |
|
||
|
||
### Request parameters
|
||
|
||
Currently no request parameters are offered for the overall status API.
|
||
|
||
### Request statuses
|
||
|
||
- `200`: Successfully retrieved the cluster status
|
||
|
||
### Response fields
|
||
|
||
| Field | Type | Description |
|
||
| --- | ---- | --- |
|
||
| `cluster_name` | string | Identifies the name of the cluster. |
|
||
| `members` | list | Contains the CTS instance objects. |
|
||
| `members.address` | string | Indicates the location of the instance. The address is only included in the response if the `high_availability.instance.address` option is configured. Refer to the [high availability instance configuration](/docs/nia/configuration#high-availability-instance) reference for additional information. |
|
||
| `members.healthy` | Boolean | Indicates the health of the instance. |
|
||
| `members.id` | string | Indicates the instance ID. |
|
||
| `members.leader` | Boolean | Identifies the cluster leader. |
|
||
| `members.service_name` | string | Identifies the name of the service that the instance represents. The value should always be `consul-terraform-sync`. |
|
||
| `request_id` | string | Unique identifier for the request. |
|
||
|
||
### Example
|
||
|
||
The following command calls the `/status/cluster` endpoint:
|
||
|
||
```shell-session
|
||
$ curl –request GET http://localhost:8553/v1/status/cluster
|
||
```
|
||
|
||
The following example response shows that there are three CTS instances. The cluster is located at `cts-02.example.com`. The leader instance, `cts-02`, is the only healthy instance:
|
||
|
||
```json
|
||
{
|
||
"cluster_name": "cluster-a",
|
||
"members": [
|
||
{
|
||
"address": "cts-02.example.com",
|
||
"healthy": true,
|
||
"id": "cts-02",
|
||
"leader": true,
|
||
"service_name": "consul-terraform-sync"
|
||
},
|
||
{
|
||
"healthy": false,
|
||
"id": "cts-03",
|
||
"leader": false,
|
||
"service_name": "consul-terraform-sync"
|
||
},
|
||
{
|
||
"healthy": false,
|
||
"id": "cts-01",
|
||
"leader": false,
|
||
"service_name": "consul-terraform-sync"
|
||
}
|
||
],
|
||
"request_id": "e1bc2236-3d0e-5f5e-dc51-164a1cf6da88"
|
||
}
|