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