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

228 lines
8.5 KiB
Markdown
Raw Blame History

---
layout: docs
page_title: Consul-Terraform-Sync Status API
description: >-
Consul-Terraform-Sync Status API
---
# 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 (CTS). For more information on the hierarchy of status information and how it is collected, see [Status Information](/docs/nia/tasks#status-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