Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
  • API Introduction
    • Consistency Modes
    • Blocking Queries
    • Filtering
    • Agent Caching

    • Overview
    • Tokens
    • Legacy Tokens
    • Policies
    • Roles
    • Auth Methods
    • Binding Rules
  • Admin Partitions
    • Overview
    • Checks
    • Services
    • Connect
  • Catalog
  • Cluster Peering
  • Config
    • Overview
    • Certificate Authority (CA)
    • Intentions
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
    • Overview
    • Area
    • Autopilot
    • Keyring
    • License
    • Raft
    • Segment
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs
Type '/' to Search

»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.

Please see the Network Coordinates internals 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.

MethodPathProduces
GET/coordinate/datacentersapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonenone

The corresponding CLI command is consul rtt -wan.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/coordinate/datacenters
$ curl \
    http://127.0.0.1:8500/v1/coordinate/datacenters

»Sample Response

[
  {
    "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]
        }
      }
    ]
  }
]
[
  {
    "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.

»Read LAN Coordinates for all nodes

This endpoint returns the LAN network coordinates for all nodes in a given datacenter.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/coordinate/nodesapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenode:read

The corresponding CLI command is consul rtt.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • segment (string: "")

    Enterprise
    - Specifies the segment to list members for. 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.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/coordinate/nodes
$ curl \
    http://127.0.0.1:8500/v1/coordinate/nodes

»Sample Response

[
  {
    "Node": "agent-one",
    "Segment": "",
    "Coord": {
      "Adjustment": 0,
      "Error": 1.5,
      "Height": 0,
      "Vec": [0, 0, 0, 0, 0, 0, 0, 0]
    }
  }
]
[
  {
    "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.

»Read LAN Coordinates for a node

This endpoint returns the LAN network coordinates for the given node.

MethodPathProduces
GET/coordinate/node/:node_nameapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenode:read

»Path Parameters

  • node_name (string: <required>) - Specifies the name of the node to return LAN network coordinates for.

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • segment (string: "")

    Enterprise
    - Specifies the segment to list members for. 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.

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/coordinate/node/agent-one
$ curl \
    http://127.0.0.1:8500/v1/coordinate/node/agent-one

»Sample Response

[
  {
    "Node": "agent-one",
    "Segment": "",
    "Coord": {
      "Adjustment": 0,
      "Error": 1.5,
      "Height": 0,
      "Vec": [0, 0, 0, 0, 0, 0, 0, 0]
    }
  }
]
[
  {
    "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.

»Update LAN Coordinates for a node

This endpoint updates the LAN network coordinates for a node in a given datacenter.

MethodPathProduces
PUT/coordinate/updateapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonenode:write

»Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

»Sample Payload

{
  "Node": "agent-one",
  "Segment": "",
  "Coord": {
    "Adjustment": 0,
    "Error": 1.5,
    "Height": 0,
    "Vec": [0, 0, 0, 0, 0, 0, 0, 0]
  }
}
{
  "Node": "agent-one",
  "Segment": "",
  "Coord": {
    "Adjustment": 0,
    "Error": 1.5,
    "Height": 0,
    "Vec": [0, 0, 0, 0, 0, 0, 0, 0]
  }
}

»Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/coordinate/update
$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/coordinate/update
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager