mirror of https://github.com/hashicorp/consul
Updates docs for network coordinates.
James Phillips
parent
de01f96d38
commit
cef9402ab9
|
|
@ -1,5 +1,5 @@
|
|||
source "https://rubygems.org"
|
||||
|
||||
ruby "2.2.2"
|
||||
ruby "2.2.3"
|
||||
|
||||
gem "middleman-hashicorp", github: "hashicorp/middleman-hashicorp"
|
||||
|
|
|
|||
|
|
@ -186,6 +186,3 @@ PLATFORMS
|
|||
|
||||
DEPENDENCIES
|
||||
middleman-hashicorp!
|
||||
|
||||
BUNDLED WITH
|
||||
1.10.6
|
||||
|
|
|
|||
|
|
@ -14,6 +14,10 @@ The Coordinate endpoint is used to query for the nework coordinates for nodes
|
|||
in the local datacenter as well as Consul servers in the local datacenter and
|
||||
remote datacenters.
|
||||
|
||||
See the [Network Coordinates](/docs/internals/coordinates.html) internals guide
|
||||
for more information on how these coordinates are computed, and for details on
|
||||
how to perform calculations with them.
|
||||
|
||||
The following endpoints are supported:
|
||||
|
||||
* [`/v1/coordinate/datacenters`](#coordinate_datacenters) : Queries for WAN coordinates of Consul servers
|
||||
|
|
@ -36,6 +40,7 @@ It returns a JSON body like this:
|
|||
"Coord": {
|
||||
"Adjustment": 0,
|
||||
"Error": 1.5,
|
||||
"Height": 0,
|
||||
"Vec": [0,0,0,0,0,0,0,0]
|
||||
}
|
||||
}
|
||||
|
|
@ -46,7 +51,7 @@ It returns a JSON body like this:
|
|||
|
||||
This endpoint serves data out of the server's local Serf data about the WAN, so
|
||||
its results may vary as requests are handled by different servers in the
|
||||
cluster.
|
||||
cluster. Also, it does not support blocking queries or any consistency modes.
|
||||
|
||||
### <a name=""coordinate_nodes></a> /v1/coordinate/nodes
|
||||
|
||||
|
|
@ -63,6 +68,7 @@ It returns a JSON body like this:
|
|||
"Coord": {
|
||||
"Adjustment": 0,
|
||||
"Error": 1.5,
|
||||
"Height": 0,
|
||||
"Vec": [0,0,0,0,0,0,0,0]
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,17 +10,11 @@ description: >
|
|||
|
||||
Command: `consul rtt`
|
||||
|
||||
The 'rtt' command estimates the network round trip time between two nodes using
|
||||
Consul's network coordinate model of the cluster. While contacting nodes as part
|
||||
of its normal gossip protocol, Consul builds up a set of network coordinates for
|
||||
all the nodes in the local datacenter (the LAN pool) and remote datacenters (the WAN
|
||||
pool). Agents forward these to the servers and once the coordinates for two nodes
|
||||
are known, it's possible to estimate the network round trip time between them using
|
||||
a simple calculation.
|
||||
The `rtt` command estimates the network round trip time between two nodes using
|
||||
Consul's network coordinate model of the cluster.
|
||||
|
||||
It is not possible to measure between LAN coordinates and WAN coordinates
|
||||
because they are maintained by independent Serf gossip pools, so they are
|
||||
not compatible.
|
||||
See the [Network Coordinates](/docs/internals/coordinates.html) internals guide
|
||||
for more information on how these coordinates are computed.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -36,7 +30,9 @@ The list of available flags are:
|
|||
coordinates. By default, the two nodes are assumed to be nodes in the local
|
||||
datacenter and the LAN coordinates are used. If the -wan option is given,
|
||||
then the WAN coordinates are used, and the node names must be suffixed by a period
|
||||
and the datacenter (eg. "myserver.dc1").
|
||||
and the datacenter (eg. "myserver.dc1"). It is not possible to measure between
|
||||
LAN coordinates and WAN coordinates, so both nodes must be in the same pool.
|
||||
|
||||
|
||||
* `-http-addr` - Address to the HTTP server of the agent you want to contact
|
||||
to send this command. If this isn't specified, the command will contact
|
||||
|
|
|
|||
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Network Coordinates"
|
||||
sidebar_current: "docs-internals-coordinates"
|
||||
description: |-
|
||||
Serf uses a network tomography system to compute network coordinates for nodes in the cluster. These coordinates are useful for easily calculating the estimated network round trip time between any two nodes in the cluster. This page documents the details of this system. The core of the network tomography system us based on Vivaldi: A Decentralized Network Coordinate System, with several improvements based on several follow-on papers.
|
||||
---
|
||||
|
||||
# Network Coordinates
|
||||
|
||||
Consul uses a [network tomography](https://en.wikipedia.org/wiki/Network_tomography)
|
||||
system to compute network coordinates for nodes in the cluster. These coordinates
|
||||
allow the network round trip time to be estimated between any two nodes using a
|
||||
a very simple calculation. This allows for many useful applications, such as finding
|
||||
the service node nearest a requesting node, or failing over to services in the next
|
||||
closest datacenter.
|
||||
|
||||
All of this is provided through the use of the [Serf library](https://www.serfdom.io/).
|
||||
Serf's network tomography is based on ["Vivaldi: A Decentralized Network Coordinate System"](http://www.cs.ucsb.edu/~ravenben/classes/276/papers/vivaldi-sigcomm04.pdf),
|
||||
with some enhancements based on other research. There are more details about
|
||||
[Serf's network coordinates here](https://www.serfdom.io/docs/internals/coordinates.html).
|
||||
|
||||
~> **Advanced Topic!** This page covers the technical details of
|
||||
the internals of Consul. You don't need to know these details to effectively
|
||||
operate and use Consul. These details are documented here for those who wish
|
||||
to learn about them without having to go spelunking through the source code.
|
||||
|
||||
## Network Coordinates in Consul
|
||||
|
||||
Network coordinates manifest in several ways inside Consul:
|
||||
|
||||
* The [`consul rtt`](/docs/commands/rtt.html) command can be used to query for the
|
||||
network round trip time between any two nodes.
|
||||
|
||||
* The [Catalog endpoints](/docs/agent/http/catalog.html) and
|
||||
[Health endpoints](/docs/agent/http/health.html) can sort the results of queries based
|
||||
on the network round trip time from a given node using a "?near=" parameter.
|
||||
|
||||
* The [Coordinate endpoint](/docs/agent/http/coordinate.html) exposes raw network
|
||||
coordinates for use in other applications.
|
||||
|
||||
Consul uses Serf to manage two different gossip pools, one for the LAN with members
|
||||
of a given datacenter, and one for the WAN which is made up of just the Consul servers
|
||||
in all datacenters. It's important to note that **network coordinates are not compatible
|
||||
between these two pools**. LAN coordinates only make sense in calculations with other
|
||||
LAN coordinates, and WAN coordinates only make sense with other WAN coordinates.
|
||||
|
||||
## Working with Coordinates
|
||||
|
||||
Computing the estimated network round trip time between any two nodes is simple
|
||||
once you have their coordinates. Here's a sample coordinate, as returned from the
|
||||
[Coordinate endpoint](/docs/agent/http/coordinate.html).
|
||||
|
||||
```
|
||||
"Coord": {
|
||||
"Adjustment": 0.1,
|
||||
"Error": 1.5,
|
||||
"Height": 0.02,
|
||||
"Vec": [0.34,0.68,0.003,0.01,0.05,0.1,0.34,0.06]
|
||||
}
|
||||
```
|
||||
|
||||
All values are floating point numbers in units of seconds, except for the error
|
||||
term which isn't used for distance calculations.
|
||||
|
||||
Here's a complete example in Go showing how to compute the distance between two
|
||||
coordinates:
|
||||
|
||||
```
|
||||
import (
|
||||
"github.com/hashicorp/serf/coordinate"
|
||||
"math"
|
||||
"time"
|
||||
)
|
||||
|
||||
func dist(a *coordinate.Coordinate, b *coordinate.Coordinate) time.Duration {
|
||||
// Coordinates will always have the same dimensionality, so this is
|
||||
// just a sanity check.
|
||||
if len(a.Vec) != len(b.Vec) {
|
||||
panic("dimensions aren't compatible")
|
||||
}
|
||||
|
||||
// Calculate the Euclidean distance plus the heights.
|
||||
sumsq := 0.0
|
||||
for i := 0; i < len(a.Vec); i++ {
|
||||
diff := a.Vec[i] - b.Vec[i]
|
||||
sumsq += diff * diff
|
||||
}
|
||||
rtt := math.Sqrt(sumsq) + a.Height + b.Height
|
||||
|
||||
// Apply the adjustment components, guarding against negatives.
|
||||
adjusted := rtt + a.Adjustment + b.Adjustment
|
||||
if adjusted > 0.0 {
|
||||
rtt = adjusted
|
||||
}
|
||||
|
||||
// Go's times are natively nanoseconds, so we convert from seconds.
|
||||
const secondsToNanoseconds = 1.0e9
|
||||
return time.Duration(rtt * secondsToNanoseconds)
|
||||
}
|
||||
```
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
|
||||
<li<%= sidebar_current("docs-upgrading-compat") %>>
|
||||
<a href="/docs/compatibility.html">Compatibility Promise</a>
|
||||
</li>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-upgrading-specific") %>>
|
||||
<a href="/docs/upgrade-specific.html">Specific Version Details</a>
|
||||
|
|
@ -38,6 +38,10 @@
|
|||
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-internals-coordinates") %>>
|
||||
<a href="/docs/internals/coordinates.html">Network Coordinates</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-internals-sessions") %>>
|
||||
<a href="/docs/internals/sessions.html">Sessions</a>
|
||||
</li>
|
||||
|
|
@ -96,8 +100,7 @@
|
|||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-leave") %>>
|
||||
<a href="/docs/commands/leave.html">leave</a>
|
||||
</li>
|
||||
<a href="/docs/commands/leave.html">leave</a></li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-lock") %>>
|
||||
<a href="/docs/commands/lock.html">lock</a>
|
||||
|
|
@ -123,6 +126,10 @@
|
|||
<a href="/docs/commands/reload.html">reload</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-rtt") %>>
|
||||
<a href="/docs/commands/rtt.html">rtt</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-watch") %>>
|
||||
<a href="/docs/commands/watch.html">watch</a>
|
||||
</li>
|
||||
|
|
@ -143,8 +150,8 @@
|
|||
<li<%= sidebar_current("docs-agent-http") %>>
|
||||
<a href="/docs/agent/http.html">HTTP API</a>
|
||||
<ul class="subnav">
|
||||
<li<%= sidebar_current("docs-agent-http-kv") %>>
|
||||
<a href="/docs/agent/http/kv.html">Key/Value store</a>
|
||||
<li<%= sidebar_current("docs-agent-http-acl") %>>
|
||||
<a href="/docs/agent/http/acl.html">ACLs</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-agent") %>>
|
||||
|
|
@ -155,20 +162,24 @@
|
|||
<a href="/docs/agent/http/catalog.html">Catalog</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-session") %>>
|
||||
<a href="/docs/agent/http/session.html">Sessions</a>
|
||||
<li<%= sidebar_current("docs-agent-http-event") %>>
|
||||
<a href="/docs/agent/http/event.html">Events</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-health") %>>
|
||||
<a href="/docs/agent/http/health.html">Health Checks</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-acl") %>>
|
||||
<a href="/docs/agent/http/acl.html">ACLs</a>
|
||||
<li<%= sidebar_current("docs-agent-http-kv") %>>
|
||||
<a href="/docs/agent/http/kv.html">Key/Value store</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-event") %>>
|
||||
<a href="/docs/agent/http/event.html">Events</a>
|
||||
<li<%= sidebar_current("docs-agent-http-coordinate") %>>
|
||||
<a href="/docs/agent/http/coordinate.html">Network Coordinates</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-session") %>>
|
||||
<a href="/docs/agent/http/session.html">Sessions</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http-status") %>>
|
||||
|
|
|
|||
Loading…
Reference in New Issue