mirror of https://github.com/status-im/consul.git
254 lines
8.0 KiB
Plaintext
254 lines
8.0 KiB
Plaintext
---
|
|
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/products/consul/) version 0.8.0 and later. )
|
|
|
|
<%= enterprise_alert :consul %>
|
|
|
|
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/advanced-federation.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
|
|
update Update the configuration of a network area
|
|
```
|
|
|
|
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.
|
|
|
|
* `-use-tls=<value>` Specifies whether gossip over this area should be encrypted with
|
|
TLS if possible. Must be either `true` or `false`.
|
|
|
|
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.
|
|
|
|
## update
|
|
|
|
This command updates the configuration of network area.
|
|
|
|
Usage: `consul operator area update [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>` - 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.
|
|
|
|
* `-use-tls=<value>` Specifies whether gossip over this area should be encrypted with
|
|
TLS if possible. Must be either `true` or `false`.
|
|
|
|
The output looks like this:
|
|
|
|
```
|
|
Updated area "d2872ec5-68ea-b862-b75d-0bee99aca100"
|
|
```
|
|
|
|
The return code will indicate success or failure.
|