luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/docs/nia/api/status.mdx

303 lines
12 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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](/consul/docs/nia/tasks#status-information).
If CTS is configured [for high availability](/consul/docs/nia/usage/run-ha), you can send requests to the [`/status/cluster` endpoint path](#cluster-status) 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](/consul/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
No request parameters are available for this endpoint.
### Response statuses
- `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](/consul/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
- `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](/consul/docs/nia/api/status#event)] | List of stored events that inform the task's status. See [section below](/consul/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](/consul/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 high-availability clusters and its members, such as health status and leadership. This endpoint is only supported when using CTS in [high availability mode](/consul/docs/nia/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](/consul/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 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.
| Field | Type | Description |
| --- | ---- | --- |
| `cluster_name` | string | Identifies the name of the cluster. |
| `members` | list[[member](#member-objects)] | Contains a list of [member objects](#member-objects). Each object in the `members` list represents a CTS instance. |
#### Member objects
The following table describes the fields available for objects in the `members` array.
| Field | Type | Description |
| --- | ---- | --- |
| `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 on the leader instance. Refer to the [high availability instance configuration](/consul/docs/nia/configuration#high-availability-instance) reference for additional information. |
| `healthy` | boolean | Indicates the health of the service instance health. Refer to [Service Registration](/consul/docs/nia/configuration#service-registration) for additional information. |
| `id` | string | Indicates the service registration ID. Refer to [Service Registration](/consul/docs/nia/configuration#service-registration) for additional information. |
| `leader` | boolean | Identifies the cluster leader. |
| `service_name` | string | Identifies the name of the service that the instance represents. The value is set by the `service_name` field in the [Service Registration](/consul/docs/nia/configuration#service-registration) configuration. |
### 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 three CTS instances. The cluster leader is `cts-02` and is advertising that its address is `cts-02.example.com`:
```json
{
"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"
}
```
Reference in New Issue View Git Blame Copy Permalink