status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/nia/api/status.mdx

228 lines
8.7 KiB
Plaintext
Raw Blame History

---
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, see [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, but requests to a follower instance 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.
## 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:
```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.
### Example: 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"
}
}
```
### Example: 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"
}
}
]
}
}
```
Reference in New Issue View Git Blame Copy Permalink