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

246 lines
7.2 KiB
Plaintext
Raw Normal View History

Update API docs
2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Coordinate - HTTP API
description: |-
The /coordinate endpoints query for the network coordinates for nodes in the
local datacenter as well as Consul servers in the local datacenter and remote
datacenters.
---
# Coordinate HTTP Endpoint
The `/coordinate` endpoints query for the network coordinates for nodes in the
local datacenter as well as Consul servers in the local datacenter and remote
datacenters.
docs: Avoid redirects by pointing links to new URLs Avoid HTTP redirects for internal site links by updating old URLs to point to the new location for the target content.
2022-01-10 23:36:16 +00:00
Please see the [Network Coordinates](/docs/architecture/coordinates) internals
Update API docs
2017-04-04 16:33:22 +00:00
guide for more information on how these coordinates are computed, and for
details on how to perform calculations with them.
## Read WAN Coordinates
This endpoint returns the WAN network coordinates for all Consul servers,
organized by datacenters. It serves data out of the server's local Serf data, so
its results may vary as requests are handled by different servers in the
cluster.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------------- | ------------------ |
| `GET` | `/coordinate/datacenters` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
docs: fix api docs anchor links
2022-10-18 19:49:07 +00:00
[required ACLs](/api-docs/api-structure#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `none` |
Update API docs
2017-04-04 16:33:22 +00:00
docs: don't treat CLI cmd cross-ref as info box
2022-01-15 17:29:35 +00:00
The corresponding CLI command is [`consul rtt -wan`](/commands/rtt#wan).
Editing links and grammer changes
2022-01-10 19:21:32 +00:00
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/coordinate/datacenters
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"Datacenter": "dc1",
"AreaID": "WAN",
"Coordinates": [
{
"Node": "agent-one",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0, 0, 0, 0, 0, 0, 0, 0]
}
}
]
}
]
```
In **Consul Enterprise**, this will include coordinates for user-added network
areas as well, as indicated by the `AreaID`. Coordinates are only compatible
within the same area.
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
## Read LAN Coordinates for all nodes
Update API docs
2017-04-04 16:33:22 +00:00
This endpoint returns the LAN network coordinates for all nodes in a given
datacenter.
docs: mention filtered by ACLs in coordinate API
2022-03-02 14:00:13 +00:00
@include 'http_api_results_filtered_by_acls.mdx'
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `GET` | `/coordinate/nodes` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
docs: fix api docs anchor links
2022-10-18 19:49:07 +00:00
[required ACLs](/api-docs/api-structure#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `node:read` |
Update API docs
2017-04-04 16:33:22 +00:00
docs: don't treat CLI cmd cross-ref as info box
2022-01-15 17:29:35 +00:00
The corresponding CLI command is [`consul rtt`](/commands/rtt).
Editing links and grammer changes
2022-01-10 19:21:32 +00:00
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
### Query Parameters
Update API docs
2017-04-04 16:33:22 +00:00
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
the datacenter of the agent being queried.
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for.
Fill out the tests around coordinate/node functionality
2017-10-31 22:08:14 +00:00
If left blank, this will query for the default segment when connecting to a server and
the agent's own segment when connecting to a client (clients can only be part of one
network segment). When querying a server, setting this to the special string `_all`
will show members in all segments.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/coordinate/nodes
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"Node": "agent-one",
Adds open source side of network segments (feature is Enterprise-only).
2017-08-14 14:36:07 +00:00
"Segment": "",
Update API docs
2017-04-04 16:33:22 +00:00
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0, 0, 0, 0, 0, 0, 0, 0]
}
}
]
```
Adds open source side of network segments (feature is Enterprise-only).
2017-08-14 14:36:07 +00:00
In **Consul Enterprise**, this may include multiple coordinates for the same node,
each marked with a different `Segment`. Coordinates are only compatible within the same
segment.
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
## Read LAN Coordinates for a node
Fill out the tests around coordinate/node functionality
2017-10-31 22:08:14 +00:00
This endpoint returns the LAN network coordinates for the given node.
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `GET` | `/coordinate/node/:node_name` | `application/json` |
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
docs: fix api docs anchor links
2022-10-18 19:49:07 +00:00
[required ACLs](/api-docs/api-structure#authentication).
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `node:read` |
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
### Path Parameters
- `node_name` `(string: <required>)` - Specifies the name of the node to return LAN network coordinates for.
### Query Parameters
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
the datacenter of the agent being queried.
Add callouts to Enterprise features (#7548) Label all enterprise-related content with Enterprise badge/callout. Resolves #6887 Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
2020-04-23 22:13:18 +00:00
- `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for.
Fill out the tests around coordinate/node functionality
2017-10-31 22:08:14 +00:00
If left blank, this will query for the default segment when connecting to a server and
the agent's own segment when connecting to a client (clients can only be part of one
network segment). When querying a server, setting this to the special string `_all`
will show members in all segments.
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/coordinate/node/agent-one
agent: add /v1/coordianate/node/:node endpoint This patch adds a /v1/coordinate/node/:node endpoint to get the network coordinates for a single node in the network. Since Consul Enterprise supports network segments it is still possible to receive mutiple entries for a single node - one per segment.
2017-10-26 12:24:42 +00:00
```
### Sample Response
```json
[
{
"Node": "agent-one",
"Segment": "",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0, 0, 0, 0, 0, 0, 0, 0]
}
}
]
```
In **Consul Enterprise**, this may include multiple coordinates for the same node,
each marked with a different `Segment`. Coordinates are only compatible within the same
segment.
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
## Update LAN Coordinates for a node
This endpoint updates the LAN network coordinates for a node in a given
datacenter.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | -------------------- | ------------------ |
| `PUT` | `/coordinate/update` | `application/json` |
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
docs: fix api docs anchor links
2022-10-18 19:49:07 +00:00
[required ACLs](/api-docs/api-structure#authentication).
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `node:write` |
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
### Query Parameters
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
docs: split HTTP API params into sections by type Path parameters, query parameters, and request body parameters are now shown in separate sections rather than combined into one general parameters section. This makes it much easier to understand quickly where a parameter should be provided.
2022-05-10 15:51:11 +00:00
the datacenter of the agent being queried.
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
### Sample Payload
docs: Update code blocks across website * Use CodeTabs for examples in multiple formats. * Ensure correct language on code fences. * Use CodeBlockConfig for examples with filenames, or which need highlighted content.
2021-07-31 01:37:33 +00:00
```json
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
{
"Node": "agent-one",
"Segment": "",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0, 0, 0, 0, 0, 0, 0, 0]
}
}
```
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
$ curl \
--request PUT \
--data @payload.json \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/coordinate/update
Add docs for the coordinate update endpoint
2017-10-27 03:17:46 +00:00
```