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

238 lines
6.9 KiB
Plaintext
Raw Normal View History

Update API docs
2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Coordinate - HTTP API
remove 'sidebar_current' from frontmatter
2020-04-13 18:40:26 +00:00
sidebar_title: Coordinates
Update API docs
2017-04-04 16:33:22 +00:00
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.
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
Please see the [Network Coordinates](/docs/internals/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
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### 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.
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
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
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
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------------ | ------------------ |
| `GET` | `/coordinate/node/:node` | `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
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
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
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#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
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Payload
```text
{
"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
```