mirror of https://github.com/status-im/consul.git
Adds network area CLI documentation.
This commit is contained in:
James Phillips
parent
1296e40ad5
commit
0b0eba8e97
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue