status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

applied AJs feedback and made a few additional improvements

This commit is contained in:
trujillo-adam 2022-09-06 16:00:09 -07:00
parent 321044312f
commit 120e8b43ec
3 changed files with 60 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
website/content/docs/nia/api/index.mdx
View File

@ -2,32 +2,29 @@
layout: docs
page_title: Consul-Terraform-Sync API
description: >-
How to use the Consul-Terraform-Sync API
Consul-Terraform-Sync provides an API interface that lets you query CTS instance health, check CTS instance status, and run CTS tasks.
---
# Consul-Terraform-Sync API
# Consul-Terraform-Sync API Overview
When running in [daemon mode](/docs/nia/cli#daemon-mode), Consul-Terraform-Sync (CTS) serves an HTTP API interface. Details of the available API endpoints is available in the navigation to the left.
Consul-Terraform-Sync (CTS) provides an HTTP API interface for querying CTS instances and running and managing tasks.
### Port
## Port
The API is served at the default port `8558` or a different port if set with [`port` configuration](/docs/nia/configuration#port)
### Version Prefix
## Version prefix
All API routes are prefixed with `/v1/`. This documentation is for v1 of the API, which is the only version currently.
Example: `localhost:8558/v1/status`
### Error
## Request ID
Successful API requests will receive a 2XX success status code. For other unsuccessful status codes, when possible, more details will be provided in a response body containing an error object.
Each call to a CTS API endpoint returns a `request_id` field. The field is a string generated by the API. Example:
Example: Status 400 Bad Request
```json
{
"error": {
"message": "example error message: unsupported status parameter value"
}
}
```
`"request_id": "e1bc2236-3d0e-5f5e-dc51-164a1cf6da88"`
## Error messages
The API sends a response code in the 200 range if the call is successful. If the call is unsuccessful, the API sends an error message that includes additional information when possible. Refer to [Error Messages](/docs/nia/usage/errors-ref) for additional information.

46
website/content/docs/nia/api/status.mdx
View File

@ -8,7 +8,7 @@ description: >-
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.
If CTS is configured [for high availability](/docs/nia/usage/run-ha), you can send a request to the [`/status/cluster` endpoint](#cluster-status) of any instance to get information about the cluster. Requests to the `status` endpoint return a 400 error, however, if high availability is enabled and 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](/docs/nia/usage/errors-ref) for more information.
## Status for all tasks
@ -19,13 +19,12 @@ This endpoint returns the overall status information for all tasks.
| `GET` | `/status` | `application/json` |
### Request parameters
Currently no request parameters are offered for the overall status API.
No request parameters are available for this endpoint.
### Response statuses
| Status | Reason |
| ------ | ---------------- |
| 200 | Successfully retrieved the status |
- `200`: Successfully retrieved the status.
### Response fields
@ -89,10 +88,8 @@ Task health status value is determined by the success or failure of all stored [
### Response statuses
| Status | Reason |
| ------ | ---------------- |
| 200 | Successfully retrieved the task status |
| 404 | Task with the given name not found |
- `200`: Successfully retrieved the task status
- `404`: Task with the given name not found
### Response fields
@ -232,7 +229,7 @@ Response:
## 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/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](/docs/nia/usage/errors-ref) for information about CTS error messages.
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](/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](/docs/nia/usage/errors-ref) for information about CTS error messages.
| Method | Path | Response format |
| ------ | ----------------- | ------------------ |
@ -248,16 +245,24 @@ Currently no request parameters are offered for the overall status API.
### 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 | 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. |
| `members` | array | Contains an array of [member objects](#member-objects). Each object in the `members` array 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](/docs/nia/configuration#high-availability-instance) reference for additional information. |
| `healthy` | boolean | Indicates the health of the service instance health. Refer to [Service Registration](#/docs/nia/configuration#service-registration) for additional information. |
| `id` | string | Indicates the service registration ID. Refer to [Service Registration](#/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. Refer to [Service Registration](#/docs/nia/configuration#service-registration) for additional information. Default is `consul-terraform-sync`. |
### Example
@ -267,7 +272,7 @@ The following command calls the `/status/cluster` endpoint:
$ 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:
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
{
@ -281,13 +286,13 @@ The following example response shows that there are three CTS instances. The clu
"service_name": "consul-terraform-sync"
},
{
"healthy": false,
"healthy": true,
"id": "cts-03",
"leader": false,
"service_name": "consul-terraform-sync"
},
{
"healthy": false,
"healthy": true,
"id": "cts-01",
"leader": false,
"service_name": "consul-terraform-sync"
@ -295,3 +300,4 @@ The following example response shows that there are three CTS instances. The clu
],
"request_id": "e1bc2236-3d0e-5f5e-dc51-164a1cf6da88"
}
```

21
website/content/docs/nia/usage/errors-ref.mdx
View File

@ -120,3 +120,24 @@ Identify and send the request to the leader CTS instance. You can identify the l
**Resolution**:
Configure CTS to run in [high availability mode](/docs/nia/usage/run-ha).
---
**Error**:
```json
{
"error": {
"message": "example error message: unsupported status parameter value"
}
}
```
**Conditions**:
- You sent a request to the `status` API endpoint.
- The request included an unsupported parameter value.
**Resolution**:
Send a new request and verify that all of the parameter values are correct.