From f8a4a873cf4a9d73b6a7046225a15398a56c1c7a Mon Sep 17 00:00:00 2001 From: James Phillips Date: Mon, 27 Mar 2017 20:59:15 -0700 Subject: [PATCH 1/4] Breaks the operator HTTP doc into sections. --- .../docs/agent/http/operator.html.markdown | 484 ++++++++++-------- 1 file changed, 257 insertions(+), 227 deletions(-) diff --git a/website/source/docs/agent/http/operator.html.markdown b/website/source/docs/agent/http/operator.html.markdown index a7ca71b740..7caabf8d60 100644 --- a/website/source/docs/agent/http/operator.html.markdown +++ b/website/source/docs/agent/http/operator.html.markdown @@ -23,13 +23,11 @@ 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 +* [Raft](#raft): Manage Raft consensus subsystem Not all endpoints support blocking queries and all consistency modes, see details in the sections below. @@ -37,229 +35,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. -### /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. - -### /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. - -### /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 ### /v1/operator/autopilot/configuration @@ -422,4 +207,249 @@ 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. \ No newline at end of file +- `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 + +### /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. + +## 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 + +### /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. + +### /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. From 1296e40ad58470b818c2398c7a7b2666d470ee03 Mon Sep 17 00:00:00 2001 From: James Phillips Date: Tue, 28 Mar 2017 01:01:22 -0700 Subject: [PATCH 2/4] Adds basic operator area HTTP documentation. --- .../docs/agent/http/operator.html.markdown | 247 +++++++++++++++++- 1 file changed, 246 insertions(+), 1 deletion(-) diff --git a/website/source/docs/agent/http/operator.html.markdown b/website/source/docs/agent/http/operator.html.markdown index 7caabf8d60..3c3133b2de 100644 --- a/website/source/docs/agent/http/operator.html.markdown +++ b/website/source/docs/agent/http/operator.html.markdown @@ -27,6 +27,7 @@ The following types of endpoints are supported: * [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, @@ -348,6 +349,250 @@ If ACLs are enabled, the client will need to supply an ACL Token with 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/`](#area-specific): Delete an area +* [`/v1/operator/area//join`](#area-join): Join Consul servers into an area +* [`/v1/operator/area//members`](#area-members): List Consul servers in an area + +### /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" ] + }, + ... +] +``` + +### /v1/operator/area/\ + +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. + +### /v1/operator/area/\/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. + +### /v1/operator/area/\/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 @@ -413,7 +658,7 @@ 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. +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. From 0b0eba8e97a0ed3c3ba56d1d99a715d8c74e8ad7 Mon Sep 17 00:00:00 2001 From: James Phillips Date: Tue, 28 Mar 2017 10:31:56 -0700 Subject: [PATCH 3/4] Adds network area CLI documentation. --- .../docs/agent/http/operator.html.markdown | 5 +- .../docs/commands/operator.html.markdown.erb | 2 + .../commands/operator/area.html.markdown.erb | 216 ++++++++++++++++++ website/source/layouts/docs.erb | 3 + 4 files changed, 224 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/commands/operator/area.html.markdown.erb diff --git a/website/source/docs/agent/http/operator.html.markdown b/website/source/docs/agent/http/operator.html.markdown index 3c3133b2de..1b8a6299d1 100644 --- a/website/source/docs/agent/http/operator.html.markdown +++ b/website/source/docs/agent/http/operator.html.markdown @@ -360,8 +360,9 @@ 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. +hub/spoke and more general trees. + +See the [Network Areas Guide](/docs/guides/areas.html) for more details. The following endpoints are supported: diff --git a/website/source/docs/commands/operator.html.markdown.erb b/website/source/docs/commands/operator.html.markdown.erb index 69bd2a826f..049d2b9f4d 100644 --- a/website/source/docs/commands/operator.html.markdown.erb +++ b/website/source/docs/commands/operator.html.markdown.erb @@ -35,6 +35,7 @@ Usage: consul operator [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) diff --git a/website/source/docs/commands/operator/area.html.markdown.erb b/website/source/docs/commands/operator/area.html.markdown.erb new file mode 100644 index 0000000000..b368694465 --- /dev/null +++ b/website/source/docs/commands/operator/area.html.markdown.erb @@ -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 [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=` - 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=` 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=` - Looks up the area to operate on by its ID. This can be given +instead of a peer datacenter. + +* `-peer-datacenter=` - 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=` - Looks up the area to operate on by its ID. This can be given +instead of a peer datacenter. + +* `-peer-datacenter=` - 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=` - Looks up the area to operate on by its ID. This can be given +instead of a peer datacenter. + +* `-peer-datacenter=` - 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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 18ca0c2100..607a90b9eb 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -142,6 +142,9 @@ > operator
    + > + area + > autopilot From dac716641e251e7bfeafbe9ee685b8d790701e1c Mon Sep 17 00:00:00 2001 From: James Phillips Date: Tue, 28 Mar 2017 11:56:55 -0700 Subject: [PATCH 4/4] Adds network areas guide. --- .../source/docs/guides/areas.html.markdown | 128 ++++++++++++++++++ .../docs/guides/datacenters.html.markdown | 20 ++- website/source/layouts/docs.erb | 10 +- 3 files changed, 152 insertions(+), 6 deletions(-) create mode 100644 website/source/docs/guides/areas.html.markdown diff --git a/website/source/docs/guides/areas.html.markdown b/website/source/docs/guides/areas.html.markdown new file mode 100644 index 0000000000..066638ba31 --- /dev/null +++ b/website/source/docs/guides/areas.html.markdown @@ -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. + diff --git a/website/source/docs/guides/datacenters.html.markdown b/website/source/docs/guides/datacenters.html.markdown index 9d7e780136..f4aeff21a1 100644 --- a/website/source/docs/guides/datacenters.html.markdown +++ b/website/source/docs/guides/datacenters.html.markdown @@ -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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 607a90b9eb..a58b0786f3 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -319,12 +319,16 @@ External Services - > - Leader Election + > + Federation (Advanced) > - Multiple Datacenters + Federation (Basic) + + + > + Leader Election >