228 lines
8.7 KiB
Plaintext
228 lines
8.7 KiB
Plaintext
---
|
|
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.
|
|
|
|
## 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"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|