luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #2839 from hashicorp/network-area-docs 

Adds network area docs.
This commit is contained in:
James Phillips 2017-03-28 11:57:57 -07:00 committed by GitHub
parent 83a9dcf418 42c8907fa6
commit bbaa3f29d5
6 changed files with 876 additions and 233 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

730
website/source/docs/agent/http/operator.html.markdown
View File

@ -23,13 +23,12 @@ these capabilities are used. For a CLI to perform these operations manually, ple
see the documentation for the [`consul operator`](/docs/commands/operator.html)
command.
The following endpoints are supported:
The following types of endpoints are supported:
* [`/v1/operator/raft/configuration`](#raft-configuration): Inspects the Raft configuration
* [`/v1/operator/raft/peer`](#raft-peer): Operates on Raft peers
* [`/v1/operator/keyring`](#keyring): Operates on gossip keyring
* [`/v1/operator/autopilot/configuration`](#autopilot-configuration): Operates on the Autopilot configuration
* [`/v1/operator/autopilot/health`](#autopilot-health): Returns the health of the servers
* [Autopilot](#autopilot): Automatically manage Consul servers
* [Keyring](#keyring): Manage gossip encryption keyring
* [Network Areas](#network-areas): Manage network areas (Enterprise-only)
* [Raft](#raft): Manage Raft consensus subsystem
Not all endpoints support blocking queries and all consistency modes,
see details in the sections below.
@ -37,229 +36,16 @@ see details in the sections below.
The operator endpoints support the use of ACL Tokens. See the
[ACL](/docs/internals/acl.html#operator) internals guide for more information.
### <a name="raft-configuration"></a> /v1/operator/raft/configuration
## Autopilot
The Raft configuration endpoint supports the `GET` method.
Autopilot is a set of new features added in Consul 0.8 to allow for automatic
operator-friendly management of Consul servers. Please see the
[Autopilot Guide](/docs/guides/autopilot.html) for more details.
#### GET Method
The following endpoints are supported:
When using the `GET` method, the request will be forwarded to the cluster
leader to retrieve its latest Raft peer configuration.
If the cluster doesn't currently have a leader an error will be returned. You
can use the `?stale` query parameter to read the Raft configuration from any
of the Consul servers.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) read privileges.
A JSON body is returned that looks like this:
```javascript
{
"Servers": [
{
"ID": "127.0.0.1:8300",
"Node": "alice",
"Address": "127.0.0.1:8300",
"Leader": true,
"Voter": true
},
{
"ID": "127.0.0.2:8300",
"Node": "bob",
"Address": "127.0.0.2:8300",
"Leader": false,
"Voter": true
},
{
"ID": "127.0.0.3:8300",
"Node": "carol",
"Address": "127.0.0.3:8300",
"Leader": false,
"Voter": true
}
],
"Index": 22
}
```
The `Servers` array has information about the servers in the Raft peer
configuration:
`ID` is the ID of the server. This is the same as the `Address` in Consul 0.7
but may be upgraded to a GUID in a future version of Consul.
`Node` is the node name of the server, as known to Consul, or "(unknown)" if
the node is stale and not known.
`Address` is the IP:port for the server.
`Leader` is either "true" or "false" depending on the server's role in the
Raft configuration.
`Voter` is "true" or "false", indicating if the server has a vote in the Raft
configuration. Future versions of Consul may add support for non-voting servers.
The `Index` value is the Raft corresponding to this configuration. The latest configuration may not yet be committed if changes are in flight.
### <a name="raft-peer"></a> /v1/operator/raft/peer
The Raft peer endpoint supports the `DELETE` method.
#### DELETE Method
Using the `DELETE` method, this endpoint will remove the Consul server with
given address from the Raft configuration.
There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This
endpoint can be used to remove the failed server so that it is no longer
affects the Raft quorum.
An `?address=` query parameter is required and should be set to the
`IP:port` for the server to remove. The port number is usually 8300, unless
configured otherwise. Nothing is required in the body of the request.
By default, the datacenter of the agent is targeted; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) write privileges.
The return code will indicate success or failure.
### <a name="keyring"></a> /v1/operator/keyring
Available in Consul 0.7.2 and later, the keyring endpoint supports the
`GET`, `POST`, `PUT` and `DELETE` methods.
This endpoint supports the use of ACL tokens using either the `X-CONSUL-TOKEN`
header or the `?token=` query parameter.
Added in Consul 0.7.4, this endpoint supports the `?relay-factor=` query parameter.
See the [Keyring Command](/docs/commands/keyring.html#_relay_factor) for more details.
#### GET Method
Using the `GET` method, this endpoint will list the gossip encryption keys
installed on both the WAN and LAN rings of every known datacenter. There is more
information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) read privileges.
A JSON body is returned that looks like this:
```javascript
[
{
"WAN": true,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
},
{
"WAN": false,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
}
]
```
`WAN` is true if the block refers to the WAN ring of that datacenter (rather than
LAN).
`Datacenter` is the datacenter the block refers to.
`Keys` is a map of each gossip key to the number of nodes it's currently installed
on.
`NumNodes` is the total number of nodes in the datacenter.
#### POST Method
Using the `POST` method, this endpoint will install a new gossip encryption key
into the cluster. There is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `POST` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the encryption key to install into the
cluster.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
#### PUT Method
Using the `PUT` method, this endpoint will change the primary gossip encryption
key. The key must already be installed before this operation can succeed. There
is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `PUT` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the primary encryption key to begin
using.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
#### DELETE Method
Using the `DELETE` method, this endpoint will remove a gossip encryption key from
the cluster. This operation may only be performed on keys which are not currently
the primary key. There is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `DELETE` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the encryption key to remove from the
cluster.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
* [`/v1/operator/autopilot/configuration`](#autopilot-configuration): Read or update Autopilot configuration
* [`/v1/operator/autopilot/health`](#autopilot-health): Read server health as determined by Autopilot
### <a name="autopilot-configuration"></a> /v1/operator/autopilot/configuration
@ -422,4 +208,494 @@ The `Servers` list holds detailed health information on each server:
- `Voter` is whether the server is a voting member of the Raft cluster.
- `StableSince` is the time this server has been in its current `Healthy` state.
- `StableSince` is the time this server has been in its current `Healthy` state.
## Keyring
The keyring endpoint allows management of the gossip encryption keyring. See
the [Gossip Protocol Guide](/docs/internals/gossip.html) for more details on the
gossip protocol and its use.
The following endpoint is supported:
* [`/v1/operator/keyring`](#keyring-endpoint): Operate on the gossip keyring
### <a name="keyring-endpoint"></a> /v1/operator/keyring
Available in Consul 0.7.2 and later, the keyring endpoint supports the
`GET`, `POST`, `PUT` and `DELETE` methods.
This endpoint supports the use of ACL tokens using either the `X-CONSUL-TOKEN`
header or the `?token=` query parameter.
Added in Consul 0.7.4, this endpoint supports the `?relay-factor=` query parameter.
See the [Keyring Command](/docs/commands/keyring.html#_relay_factor) for more details.
#### GET Method
Using the `GET` method, this endpoint will list the gossip encryption keys
installed on both the WAN and LAN rings of every known datacenter. There is more
information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) read privileges.
A JSON body is returned that looks like this:
```javascript
[
{
"WAN": true,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
},
{
"WAN": false,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
}
]
```
`WAN` is true if the block refers to the WAN ring of that datacenter (rather than
LAN).
`Datacenter` is the datacenter the block refers to.
`Keys` is a map of each gossip key to the number of nodes it's currently installed
on.
`NumNodes` is the total number of nodes in the datacenter.
#### POST Method
Using the `POST` method, this endpoint will install a new gossip encryption key
into the cluster. There is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `POST` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the encryption key to install into the
cluster.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
#### PUT Method
Using the `PUT` method, this endpoint will change the primary gossip encryption
key. The key must already be installed before this operation can succeed. There
is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `PUT` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the primary encryption key to begin
using.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
#### DELETE Method
Using the `DELETE` method, this endpoint will remove a gossip encryption key from
the cluster. This operation may only be performed on keys which are not currently
the primary key. There is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `DELETE` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the encryption key to remove from the
cluster.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
## Network Areas
~> The network area functionality described here is available only in
[Consul Enterprise](https://www.hashicorp.com/consul.html) version 0.8.0 and later.
Consul Enterprise version supports network areas, which are operator-defined relationships
between servers in two different Consul datacenters.
Unlike Consul's WAN feature, network areas use just the server RPC port for communication,
and relationships can be made between independent pairs of datacenters, so not all servers
need to be fully connected. This allows for complex topologies among Consul datacenters like
hub/spoke and more general trees.
See the [Network Areas Guide](/docs/guides/areas.html) for more details.
The following endpoints are supported:
* [`/v1/operator/area`](#area-general): Create a new area or list areas
* [`/v1/operator/area/<id>`](#area-specific): Delete an area
* [`/v1/operator/area/<id>/join`](#area-join): Join Consul servers into an area
* [`/v1/operator/area/<id>/members`](#area-members): List Consul servers in an area
### <a name="area-general"></a> /v1/operator/area
The general network area endpoint supports the `POST` and `GET` methods.
#### POST Method
When using the `POST` method, Consul will create a new network area and return
its ID if it is created successfully.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
The create operation expects a JSON request body that defines the network area,
like this example:
```javascript
{
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
}
```
`PeerDatacenter` is required and is the name of the Consul datacenter that will
be joined the Consul servers in the current datacenter to form the area. Only
one area is allowed for each possible `PeerDatacenter`, and a datacenter cannot
form an area with itself.
`RetryJoin` is a list of Consul servers to attempt to join. Servers can be given
as `IP`, `IP:port`, `hostname`, or `hostname:port`. Consul will spawn a background
task that tries to periodically join the servers in this list and will run until a
join succeeds. If this list isn't supplied, joining can be done with a call to the
[join endpoint](#area-join) once the network area is created.
The return code is 200 on success and the ID of the created network area is returned
in a JSON body:
```javascript
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
#### GET Method
When using the `GET` method, Consul will provide a listing of all network areas.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint supports blocking
queries and all consistency modes.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read privileges.
This returns a JSON list of network areas, which looks like:
```javascript
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
},
...
]
```
### <a name="area-specific"></a> /v1/operator/area/\<id\>
The specific network area endpoint supports the `GET` and `DELETE` methods.
#### GET Method
When using the `GET` method, Consul will provide a listing of a specific
network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint supports blocking
queries and all consistency modes.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read privileges.
This returns a JSON list with a single network area, which looks like:
```javascript
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
}
]
```
#### Delete Method
When using the `DELETE` method, Consul will delete a specific network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
### <a name="area-join"></a> /v1/operator/area/\<id\>/join
The network area join endpoint supports the `PUT` method.
#### PUT Method
When using the `PUT` method, Consul will attempt to join the given Consul servers
into a specific network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
The create operation expects a JSON request body with a list of Consul servers to
join, like this example:
```javascript
[ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
```
Servers can be given as `IP`, `IP:port`, `hostname`, or `hostname:port`.
The return code is 200 on success a JSON response will be returned with a summary
of the join results:
```javascript
[
{
"Address": "10.1.2.3",
"Joined": true,
"Error", ""
},
{
"Address": "10.1.2.4",
"Joined": true,
"Error", ""
},
{
"Address": "10.1.2.5",
"Joined": true,
"Error", ""
}
]
```
`Address` has the address requested to join.
`Joined` will be `true` if the Consul server at the given address was successfully
joined into the network area. Otherwise, this will be `false` and `Error` will have
a human-readable message about why the join didn't succeed.
### <a name="area-members"></a> /v1/operator/area/\<id\>/members
The network area members endpoint supports the `GET` method.
#### GET Method
When using the `GET` method, Consul will provide a listing of the Consul servers
present in a specific network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read privileges.
This returns a JSON list with details about the Consul servers present in the network
area, like this:
```javascript
[
{
"ID": "afc5d95c-1eee-4b46-b85b-0efe4c76dd48",
"Name": "node-2.dc1",
"Addr": "127.0.0.2",
"Port": 8300,
"Datacenter": "dc1",
"Role": "server",
"Build": "0.8.0",
"Protocol": 2,
"Status": "alive",
"RTT": 256478
},
...
]
```
`ID` is the node ID of the server.
`Name` is the node name of the server, with its datacenter appended.
`Addr` is the IP address of the node.
`Port` is the server RPC port of the node.
`Datacenter` is the node's Consul datacenter.
`Role` is always "server" since only Consul servers can participate in network
areas.
`Build` has the Consul version running on the node.
`Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions) being
spoken by the node.
`Status` is the current health status of the node, as determined by the network
area distributed failure detector. This will be "alive", "leaving", "left", or
"failed". A "failed" status means that other servers are not able to probe this
server over its server RPC interface.
`RTT` is an estimated network round trip time from the server answering the query
to the given server, in nanoseconds. This is computed using
[network coordinates](/docs/internals/coordinates.html).
## Raft
The Raft endpoint provides tools for Management of Raft the consensus subsystem
and cluster quorum. See the [Consensus Protocol Guide](/docs/internals/consensus.html)
for more information about Raft consensus protocol and its use.
The following endpoints are supported:
* [`/v1/operator/raft/configuration`](#raft-configuration): Inspect the Raft configuration
* [`/v1/operator/raft/peer`](#raft-peer): Remove a server from the Raft configuration
### <a name="raft-configuration"></a> /v1/operator/raft/configuration
The Raft configuration endpoint supports the `GET` method.
#### GET Method
When using the `GET` method, the request will be forwarded to the cluster
leader to retrieve its latest Raft peer configuration.
If the cluster doesn't currently have a leader an error will be returned. You
can use the `?stale` query parameter to read the Raft configuration from any
of the Consul servers.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) read privileges.
A JSON body is returned that looks like this:
```javascript
{
"Servers": [
{
"ID": "127.0.0.1:8300",
"Node": "alice",
"Address": "127.0.0.1:8300",
"Leader": true,
"Voter": true
},
{
"ID": "127.0.0.2:8300",
"Node": "bob",
"Address": "127.0.0.2:8300",
"Leader": false,
"Voter": true
},
{
"ID": "127.0.0.3:8300",
"Node": "carol",
"Address": "127.0.0.3:8300",
"Leader": false,
"Voter": true
}
],
"Index": 22
}
```
The `Servers` array has information about the servers in the Raft peer
configuration:
`ID` is the ID of the server. This is the same as the `Address` in Consul 0.7
but may be upgraded to a GUID in a future version of Consul.
`Node` is the node name of the server, as known to Consul, or "(unknown)" if
the node is stale and not known.
`Address` is the IP:port for the server.
`Leader` is either "true" or "false" depending on the server's role in the
Raft configuration.
`Voter` is "true" or "false", indicating if the server has a vote in the Raft
configuration. Future versions of Consul may add support for non-voting servers.
The `Index` value is the Raft corresponding to this configuration. The latest configuration may not yet be committed if changes are in flight.
### <a name="raft-peer"></a> /v1/operator/raft/peer
The Raft peer endpoint supports the `DELETE` method.
#### DELETE Method
Using the `DELETE` method, this endpoint will remove the Consul server with
given address from the Raft configuration.
There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This
endpoint can be used to remove the failed server so that it is no longer
affects the Raft quorum.
An `?address=` query parameter is required and should be set to the
`IP:port` for the server to remove. The port number is usually 8300, unless
configured otherwise. Nothing is required in the body of the request.
By default, the datacenter of the agent is targeted; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) write privileges.
The return code will indicate success or failure.

2
website/source/docs/commands/operator.html.markdown.erb
View File

@ -35,6 +35,7 @@ Usage: consul operator <subcommand> [options]
Subcommands:
area Provides tools for working with network areas (Enterprise-only)
autopilot Provides tools for modifying Autopilot configuration
raft Provides cluster-level tools for Consul operators
```
@ -42,5 +43,6 @@ Subcommands:
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar or one of the links below:
- [area] (/docs/commands/operator/area.html)
- [autopilot] (/docs/commands/operator/autopilot.html)
- [raft] (/docs/commands/operator/raft.html)

216
website/source/docs/commands/operator/area.html.markdown.erb Normal file
View File

@ -0,0 +1,216 @@
---
layout: "docs"
page_title: "Commands: Operator Area"
sidebar_current: "docs-commands-operator-area"
description: >
The operator area command is used to interact with Consul's network area subsystem.
---
# Consul Operator Area
Command: `consul operator area`
~> The network area functionality described here is available only in
[Consul Enterprise](https://www.hashicorp.com/consul.html) version 0.8.0 and later.
Consul Enterprise version supports network areas, which are operator-defined relationships
between servers in two different Consul datacenters. The operator area command is used to
interact with Consul's network area subsystem.
Unlike Consul's WAN feature, network areas use just the server RPC port for communication,
and relationships can be made between independent pairs of datacenters, so not all servers
need to be fully connected. This allows for complex topologies among Consul datacenters like
hub/spoke and more general trees.
See the [Network Areas Guide](/docs/guides/areas.html) for more details.
```text
Usage: consul operator area <subcommand> [options]
The operator area command is used to interact with Consul's network area
subsystem. Network areas are used to link together Consul servers in different
Consul datacenters. With network areas, Consul datacenters can be linked
together in ways other than a fully-connected mesh, as is required for Consul's
WAN.
Subcommands:
create Create a new network area
delete Remove a network area
join Join Consul servers into an existing network area
list List network areas
members Display Consul server members present in network areas
```
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read or write privileges to use these commands.
## create
This command creates a new network area.
Usage: `consul operator area create [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-peer-datacenter=<value>` - Declares the peer Consul datacenter that will make up the other
side of this network area. Network areas always involve a pair of datacenters: the datacenter
where the area was created, and the peer datacenter. This is required.
* `-retry-join=<value>` Specifies the address of a Consul server to join to, such as an IP
or hostname with an optional port number. This is optional and can be specified multiple times.
The output looks like this, displaying the ID of the newly-created network area:
```
Created area "d2872ec5-68ea-b862-b75d-0bee99aca100" with peer datacenter "other"!
```
The return code will indicate success or failure.
## delete
This command deletes an existing network area.
Usage: `consul operator area delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<value>` - Looks up the area to operate on by its ID. This can be given
instead of a peer datacenter.
* `-peer-datacenter=<value>` - Looks up the area to operate on by its peer
datacenter. This can be given instead of an ID.
The output looks like this:
```
Deleted area "154941b0-80e2-9d69-c560-ab2c02807332"!
```
The return code will indicate success or failure.
## join
This command joins Consul servers into an existing network area by address, such as
an IP or hostname with an optional port. Multiple addresses may be given.
Usage: `consul operator area join [options] ADDRESSES`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<value>` - Looks up the area to operate on by its ID. This can be given
instead of a peer datacenter.
* `-peer-datacenter=<value>` - Looks up the area to operate on by its peer
datacenter. This can be given instead of an ID.
The output looks like this:
```
Address Joined Error
10.1.2.3 false failed to connect to "10.1.2.3:8300": dial tcp 10.1.2.3:8300: i/o timeout
10.1.2.4 true (none)
10.1.2.5 true (none)
```
The `Error` field will have a human-readable error message if Consul was unable
to join the given address.
The return code will indicate success or failure.
## list
This command lists all network areas.
Usage: `consul operator area list [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
The output looks like this:
```
Area PeerDC RetryJoin
6a52a0af-62e2-dad4-da60-e66acc37096c dc2 10.1.2.3,10.1.2.4,10.1.2.5
96e33424-f5ce-9fcd-ecab-27974e36678f other (none)
```
`Area` is the ID of the network area.
`PeerDC` is the peer datacenter for the area.
`RetryJoin` is the list of servers to join, defined when the area was created.
The return code will indicate success or failure.
## members
This command displays Consul server nodes present in a network area, or all
areas if no area is specified.
Usage: `consul operator area members [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<value>` - Looks up the area to operate on by its ID. This can be given
instead of a peer datacenter.
* `-peer-datacenter=<value>` - Looks up the area to operate on by its peer
datacenter. This can be given instead of an ID.
The output looks like this:
```
Area Node Address Status Build Protocol DC RTT
6a52a0af-62e2-dad4-da60-e66acc37096c node-1.dc1 127.0.0.1:8300 alive 0.8.0 2 dc1 0s
6a52a0af-62e2-dad4-da60-e66acc37096c node-2.dc1 127.0.0.2:8300 alive 0.8.0 2 dc1 594.191µs
96e33424-f5ce-9fcd-ecab-27974e36678f node-1.dc1 127.0.0.1:8300 alive 0.8.0 2 dc1 0s
96e33424-f5ce-9fcd-ecab-27974e36678f node-2.dc1 127.0.0.2:8300 alive 0.8.0 2 dc1 634.109µs
```
`Area` is the ID of the network area.
`Node` is the name of the node.
`Address` is the IP and server RPC port for the node.
`Status` is the current health status of the node, as determined by the network
area distributed failure detector. This will be "alive", "leaving", "left", or
"failed". A "failed" status means that other servers are not able to probe this
server over its server RPC interface.
`Build` has the Consul version running on the node.
`Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions) being
spoken by the node.
`DC` is the node's Consul datacenter.
`RTT` is an estimated network round trip time from the server answering the query
to the given server, in a human-readable format. This is computed using
[network coordinates](/docs/internals/coordinates.html).
The return code will indicate success or failure.

128
website/source/docs/guides/areas.html.markdown Normal file
View File

@ -0,0 +1,128 @@
---
layout: "docs"
page_title: "Multiple Datacenters - Advanced Federation with Network Areas"
sidebar_current: "docs-guides-areas"
description: |-
One of the key features of Consul is its support for multiple datacenters. The architecture of Consul is designed to promote low coupling of datacenters so that connectivity issues or failure of any datacenter does not impact the availability of Consul in other datacenters. This means each datacenter runs independently, each having a dedicated group of servers and a private LAN gossip pool.
---
# Multiple Datacenters
## Advanced Federation with Network areas
~> The network area functionality described here is available only in
[Consul Enterprise](https://www.hashicorp.com/consul.html) version 0.8.0 and later.
One of the key features of Consul is its support for multiple datacenters.
The [architecture](/docs/internals/architecture.html) of Consul is designed to
promote a low coupling of datacenters so that connectivity issues or
failure of any datacenter does not impact the availability of Consul in other
datacenters. This means each datacenter runs independently, each having a dedicated
group of servers and a private LAN [gossip pool](/docs/internals/gossip.html).
This guide covers the advanced form of federating Consul clusters using the new
network areas capability added in [Consul Enterprise](https://www.hashicorp.com/consul.html)
version 0.8.0. For the basic form of federation available in the open source version
of Consul, please see the [Basic Federation Guide](/docs/guides/datacenters.html)
for more details.
## Network Areas
Consul's [Basic Federation](/docs/guides/datacenters.html) support relies on all
Consul servers in all datacenters having full mesh connectivity via server RPC
(8300/tcp) and Serf WAN (8302/tcp and 8302/udp). Securing this setup requires TLS
in combination with managing a gossip keyring. With massive Consul deployments, it
becomes tricky to support a full mesh with all Consul servers, and to manage the
keyring.
Consul Enterprise version 0.8.0 added support for a new federation model based on
operator-created network areas. Network areas specify a relationship between a
pair of Consul datacenters. Operators create reciprocal areas on each side of the
relationship and then join them together, so a given Consul datacenter can participate
in many areas, even when some of the peer areas cannot contact each other. This
allows for more flexible relationships between Consul datacenters, such as hub/spoke
or more general tree structures. Traffic between areas is all performed via server
RPC (8300/tcp) so it can be secured with just TLS.
Currently, Consul will only route RPC requests to datacenters it is immediately adjacent
to via an area (or via the WAN), but future versions of Consul may add routing support.
The following can be used to manage network areas:
* [Network Areas HTTP Endpoint](/docs/agent/http/operator.html#network-areas)
* [Network Areas Operator CLI](/docs/commands/operator/area.html)
## Network Areas and the WAN Gossip Pool
Networks areas can be used alongside the Consul's [Basic Federation](/docs/guides/datacenters.html)
model and the WAN gossip pool. This helps ease migration, and clusters like the
[ACL datacenter](/docs/agent/options.html#acl_datacenter) are more easily managed via
the WAN because they need to be available to all Consul datacenters.
A peer datacenter can connected via the WAN gossip pool and a network area at the
same time, and RPCs will be forwarded as long as servers are available in either.
## Getting Started
To get started, follow the [bootstrapping guide](/docs/guides/bootstrapping.html) to
start each datacenter. After bootstrapping, we should have two datacenters now which
we can refer to as `dc1` and `dc2`. Note that datacenter names are opaque to Consul;
they are simply labels that help human operators reason about the Consul clusters.
A compatible pair of areas must be created in each datacenter:
```text
(dc1) $ consul operator area create -peer-datacenter=dc2
Created area "cbd364ae-3710-1770-911b-7214e98016c0" with peer datacenter "dc2"!
```
```text
(dc2) $ consul operator area create -peer-datacenter=dc1
Created area "2aea3145-f1e3-cb1d-a775-67d15ddd89bf" with peer datacenter "dc1"!
```
Now you can query for the members of the area:
```text
$ consul operator area members
Area Node Address Status Build Protocol DC RTT
cbd364ae-3710-1770-911b-7214e98016c0 node-1.dc1 127.0.0.1:8300 alive 0.8.0_entrc1 2 dc1 0s
```
Consul will automatically make sure that all servers within the datacenter where
the area was created are joined to the area using the LAN information. We need to
join with at least one Consul server in the other datacenter to complete the area:
```text
$ consul operator area join -peer-datacenter=dc2 127.0.0.2
Address Joined Error
127.0.0.2 true (none)
```
With a successful join, we should now see the remote Consul servers as part of the
area's members:
```text
$ consul operator area members
Area Node Address Status Build Protocol DC RTT
cbd364ae-3710-1770-911b-7214e98016c0 node-1.dc1 127.0.0.1:8300 alive 0.8.0_entrc1 2 dc1 0s
cbd364ae-3710-1770-911b-7214e98016c0 node-2.dc2 127.0.0.2:8300 alive 0.8.0_entrc1 2 dc2 581.649µs
```
Now we can route RPC commands in both directions. Here's a sample command to set a KV
entry in dc2 from dc1:
```text
$ consul kv put -datacenter=dc2 hello world
Success! Data written to: hello
```
There are a few networking requirements that must be satisfied for this to
work. Of course, all server nodes must be able to talk to each other via their server
RPC ports (8300/tcp). If service discovery is to be used across datacenters, the
network must be able to route traffic between IP addresses across regions as well.
Usually, this means that all datacenters must be connected using a VPN or other
tunneling mechanism. Consul does not handle VPN or NAT traversal for you.
The [`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration
provides a basic address rewriting capability.

20
website/source/docs/guides/datacenters.html.markdown
View File

@ -1,12 +1,13 @@
---
layout: "docs"
page_title: "Multiple Datacenters"
page_title: "Multiple Datacenters - Basic Federation with the WAN Gossip Pool"
sidebar_current: "docs-guides-datacenters"
description: |-
One of the key features of Consul is its support for multiple datacenters. The architecture of Consul is designed to promote low coupling of datacenters so that connectivity issues or failure of any datacenter does not impact the availability of Consul in other datacenters. This means each datacenter runs independently, each having a dedicated group of servers and a private LAN gossip pool.
---
# Multiple Datacenters
## Basic Federation with the WAN Gossip Pool
One of the key features of Consul is its support for multiple datacenters.
The [architecture](/docs/internals/architecture.html) of Consul is designed to
@ -15,6 +16,14 @@ failure of any datacenter does not impact the availability of Consul in other
datacenters. This means each datacenter runs independently, each having a dedicated
group of servers and a private LAN [gossip pool](/docs/internals/gossip.html).
This guide covers the basic form of federating Consul clusters using a single
WAN gossip pool, interconnecting all Consul servers.
[Consul Enterprise](https://www.hashicorp.com/consul.html) version 0.8.0 added support
for an advanced multiple datacenter capability. Please see the
[Advanced Federation Guide](/docs/guides/areas.html) for more details.
## Getting Started
To get started, follow the [bootstrapping guide](/docs/guides/bootstrapping.html) to
start each datacenter. After bootstrapping, we should have two datacenters now which
we can refer to as `dc1` and `dc2`. Note that datacenter names are opaque to Consul;
@ -44,7 +53,9 @@ The [`join`](/docs/commands/join.html) command is used with the `-wan` flag to i
we are attempting to join a server in the WAN gossip pool. As with LAN gossip, you only
need to join a single existing member, and the gossip protocol will be used to exchange
information about all known members. For the initial setup, however, each server
will only know about itself and must be added to the cluster.
will only know about itself and must be added to the cluster. Consul 0.8.0 added WAN join
flooding, so if one Consul server in a datacenter joins the WAN, it will automatically
join the other servers in its local datacenter that it knows about via the LAN.
Once the join is complete, the [`members`](/docs/commands/members.html) command can be
used to verify that all server nodes gossiping over WAN.
@ -82,4 +93,7 @@ the gossip protocol as well as RPC forwarding will not work. If service discover
is to be used across datacenters, the network must be able to route traffic
between IP addresses across regions as well. Usually, this means that all datacenters
must be connected using a VPN or other tunneling mechanism. Consul does not handle
VPN, address rewriting, or NAT traversal for you.
VPN or NAT traversal for you.
The [`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration
provides a basic address rewriting capability.

13
website/source/layouts/docs.erb
View File

@ -142,6 +142,9 @@
<li<%= sidebar_current("docs-commands-operator") %>>
<a href="/docs/commands/operator.html">operator</a>
<ul class="subnav">
<li<%= sidebar_current("docs-commands-operator-area") %>>
<a href="/docs/commands/operator/area.html">area</a>
</li>
<li<%= sidebar_current("docs-commands-operator-autopilot") %>>
<a href="/docs/commands/operator/autopilot.html">autopilot</a>
</li>
@ -316,12 +319,16 @@
<a href="/docs/guides/external.html">External Services</a>
</li>
<li<%= sidebar_current("docs-guides-leader") %>>
<a href="/docs/guides/leader-election.html">Leader Election</a>
<li<%= sidebar_current("docs-guides-areas") %>>
<a href="/docs/guides/areas.html">Federation (Advanced)</a>
</li>
<li<%= sidebar_current("docs-guides-datacenters") %>>
<a href="/docs/guides/datacenters.html">Multiple Datacenters</a>
<a href="/docs/guides/datacenters.html">Federation (Basic)</a>
</li>
<li<%= sidebar_current("docs-guides-leader") %>>
<a href="/docs/guides/leader-election.html">Leader Election</a>
</li>
<li<%= sidebar_current("docs-guides-outage") %>>