github.com/clly/consul@v1.4.5/website/source/api/coordinate.html.md (about) 1 --- 2 layout: api 3 page_title: Coordinate - HTTP API 4 sidebar_current: api-coordinate 5 description: |- 6 The /coordinate endpoints query for the network coordinates for nodes in the 7 local datacenter as well as Consul servers in the local datacenter and remote 8 datacenters. 9 --- 10 11 # Coordinate HTTP Endpoint 12 13 The `/coordinate` endpoints query for the network coordinates for nodes in the 14 local datacenter as well as Consul servers in the local datacenter and remote 15 datacenters. 16 17 Please see the [Network Coordinates](/docs/internals/coordinates.html) internals 18 guide for more information on how these coordinates are computed, and for 19 details on how to perform calculations with them. 20 21 ## Read WAN Coordinates 22 23 This endpoint returns the WAN network coordinates for all Consul servers, 24 organized by datacenters. It serves data out of the server's local Serf data, so 25 its results may vary as requests are handled by different servers in the 26 cluster. 27 28 | Method | Path | Produces | 29 | ------ | ---------------------------- | -------------------------- | 30 | `GET` | `/coordinate/datacenters` | `application/json` | 31 32 The table below shows this endpoint's support for 33 [blocking queries](/api/index.html#blocking-queries), 34 [consistency modes](/api/index.html#consistency-modes), 35 [agent caching](/api/index.html#agent-caching), and 36 [required ACLs](/api/index.html#acls). 37 38 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 39 | ---------------- | ----------------- | ------------- | ------------ | 40 | `NO` | `none` | `none` | `none` | 41 42 ### Sample Request 43 44 ```text 45 $ curl \ 46 http://127.0.0.1:8500/v1/coordinate/datacenters 47 ``` 48 49 ### Sample Response 50 51 ```json 52 [ 53 { 54 "Datacenter": "dc1", 55 "AreaID": "WAN", 56 "Coordinates": [ 57 { 58 "Node": "agent-one", 59 "Coord": { 60 "Adjustment": 0, 61 "Error": 1.5, 62 "Height": 0, 63 "Vec": [0, 0, 0, 0, 0, 0, 0, 0] 64 } 65 } 66 ] 67 } 68 ] 69 ``` 70 71 In **Consul Enterprise**, this will include coordinates for user-added network 72 areas as well, as indicated by the `AreaID`. Coordinates are only compatible 73 within the same area. 74 75 ## Read LAN Coordinates for all nodes 76 77 This endpoint returns the LAN network coordinates for all nodes in a given 78 datacenter. 79 80 | Method | Path | Produces | 81 | ------ | ---------------------------- | -------------------------- | 82 | `GET` | `/coordinate/nodes` | `application/json` | 83 84 The table below shows this endpoint's support for 85 [blocking queries](/api/index.html#blocking-queries), 86 [consistency modes](/api/index.html#consistency-modes), 87 [agent caching](/api/index.html#agent-caching), and 88 [required ACLs](/api/index.html#acls). 89 90 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 91 | ---------------- | ----------------- | ------------- | ------------ | 92 | `YES` | `all` | `none` | `node:read` | 93 94 ### Parameters 95 96 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 97 the datacenter of the agent being queried. This is specified as part of the 98 URL as a query parameter. 99 - `segment` `(string: "")` - (Enterprise-only) Specifies the segment to list members for. 100 If left blank, this will query for the default segment when connecting to a server and 101 the agent's own segment when connecting to a client (clients can only be part of one 102 network segment). When querying a server, setting this to the special string `_all` 103 will show members in all segments. 104 105 ### Sample Request 106 107 ```text 108 $ curl \ 109 http://127.0.0.1:8500/v1/coordinate/nodes 110 ``` 111 112 ### Sample Response 113 114 ```json 115 [ 116 { 117 "Node": "agent-one", 118 "Segment": "", 119 "Coord": { 120 "Adjustment": 0, 121 "Error": 1.5, 122 "Height": 0, 123 "Vec": [0, 0, 0, 0, 0, 0, 0, 0] 124 } 125 } 126 ] 127 ``` 128 129 In **Consul Enterprise**, this may include multiple coordinates for the same node, 130 each marked with a different `Segment`. Coordinates are only compatible within the same 131 segment. 132 133 ## Read LAN Coordinates for a node 134 135 This endpoint returns the LAN network coordinates for the given node. 136 137 | Method | Path | Produces | 138 | ------ | ---------------------------- | -------------------------- | 139 | `GET` | `/coordinate/node/:node` | `application/json` | 140 141 The table below shows this endpoint's support for 142 [blocking queries](/api/index.html#blocking-queries), 143 [consistency modes](/api/index.html#consistency-modes), 144 [agent caching](/api/index.html#agent-caching), and 145 [required ACLs](/api/index.html#acls). 146 147 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 148 | ---------------- | ----------------- | ------------- | ------------ | 149 | `YES` | `all` | `none` | `node:read` | 150 151 ### Parameters 152 153 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 154 the datacenter of the agent being queried. This is specified as part of the 155 URL as a query parameter. 156 - `segment` `(string: "")` - (Enterprise-only) Specifies the segment to list members for. 157 If left blank, this will query for the default segment when connecting to a server and 158 the agent's own segment when connecting to a client (clients can only be part of one 159 network segment). When querying a server, setting this to the special string `_all` 160 will show members in all segments. 161 162 ### Sample Request 163 164 ```text 165 $ curl \ 166 http://127.0.0.1:8500/v1/coordinate/node/agent-one 167 ``` 168 169 ### Sample Response 170 171 ```json 172 [ 173 { 174 "Node": "agent-one", 175 "Segment": "", 176 "Coord": { 177 "Adjustment": 0, 178 "Error": 1.5, 179 "Height": 0, 180 "Vec": [0, 0, 0, 0, 0, 0, 0, 0] 181 } 182 } 183 ] 184 ``` 185 186 In **Consul Enterprise**, this may include multiple coordinates for the same node, 187 each marked with a different `Segment`. Coordinates are only compatible within the same 188 segment. 189 190 ## Update LAN Coordinates for a node 191 192 This endpoint updates the LAN network coordinates for a node in a given 193 datacenter. 194 195 | Method | Path | Produces | 196 | ------ | ---------------------------- | -------------------------- | 197 | `PUT` | `/coordinate/update` | `application/json` | 198 199 The table below shows this endpoint's support for 200 [blocking queries](/api/index.html#blocking-queries), 201 [consistency modes](/api/index.html#consistency-modes), 202 [agent caching](/api/index.html#agent-caching), and 203 [required ACLs](/api/index.html#acls). 204 205 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 206 | ---------------- | ----------------- | ------------- | ------------ | 207 | `NO` | `none` | `none` | `node:write` | 208 209 ### Parameters 210 211 - `dc` `(string: "")` - Specifies the datacenter to query. This will default to 212 the datacenter of the agent being queried. This is specified as part of the 213 URL as a query parameter. 214 215 ### Sample Payload 216 217 ```text 218 { 219 "Node": "agent-one", 220 "Segment": "", 221 "Coord": { 222 "Adjustment": 0, 223 "Error": 1.5, 224 "Height": 0, 225 "Vec": [0, 0, 0, 0, 0, 0, 0, 0] 226 } 227 } 228 ``` 229 230 ### Sample Request 231 232 ```text 233 $ curl \ 234 --request PUT \ 235 --data @payload.json \ 236 http://127.0.0.1:8500/v1/coordinate/update 237 ```