Consul Operator Area
Command: consul operator area
This feature requires Consul Enterprise(opens in new tab).
Consul Enterprise 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 for more details.
If ACLs are enabled, the client will need to supply an ACL Token with operator
read or write privileges to use these commands.
create
Corresponding HTTP API Endpoint: [POST] /v1/operator/area
This command creates a new network area.
The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.
ACL Required |
---|
operator:write |
Usage: consul operator area create [options]
The following example output shows the ID of the newly-created network area:
The return code indicates success or failure.
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 eithertrue
orfalse
.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.
delete
Corresponding HTTP API Endpoint: [DELETE] /v1/operator/area/:uuid
This command deletes an existing network area.
The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.
ACL Required |
---|
operator:write |
Usage: consul operator area delete [options]
The output looks like this:
The return code indicates success or failure.
Command Options
-id=<value>
- Specifies the ID of a network area to operate on. Use this option as an alternative to-peer-datacenter
.-peer-datacenter=<value>
- Specifies the peer datacenter of a network area to operate on. Use this option as an alternative to-id
.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.
join
Corresponding HTTP API Endpoint: [PUT] /v1/operator/area/:uuid/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.
The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.
ACL Required |
---|
operator:write |
Usage: consul operator area join [options] ADDRESSES
The output looks like this:
The Error
field will have a human-readable error message if Consul was unable
to join the given address.
The return code indicates success or failure.
Command Options
-id=<value>
- Specifies the ID of a network area to operate on. Use this option as an alternative to-peer-datacenter
.-peer-datacenter=<value>
- Specifies the peer datacenter of a network area to operate on. Use this option as an alternative to-id
.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.
list
Corresponding HTTP API Endpoint: [GET] /v1/operator/area
This command lists all network areas.
The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.
ACL Required |
---|
operator:read |
Usage: consul operator area list [options]
The output looks like this:
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 indicates success or failure.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.
members
Corresponding HTTP API Endpoint: [GET] /v1/operator/area/:uuid/members
This command displays Consul server nodes present in a network area, or all areas if no area is specified.
The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.
ACL Required |
---|
operator:read |
Usage: consul operator area members [options]
The output looks like this:
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 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.
The return code indicates success or failure.
Command Options
-id=<value>
- Specifies the ID of a network area to operate on. Use this option as an alternative to-peer-datacenter
.-peer-datacenter=<value>
- Specifies the peer datacenter of a network area to operate on. Use this option as an alternative to-id
.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.
update
Corresponding HTTP API Endpoint: [PUT] /v1/operator/area/:uuid
This command updates the configuration of network area.
The table below shows this command's required ACLs. Configuration of blocking queries and agent caching are not supported from commands, but may be from the corresponding HTTP endpoint.
ACL Required |
---|
operator:write |
Usage: consul operator area update [options]
The output looks like this:
The return code indicates success or failure.
Command Options
-id=<value>
- Specifies the ID of a network area to operate on. Use this option as an alternative to-peer-datacenter
.-peer-datacenter=<value>
- Specifies the peer datacenter of a network area to operate on. Use this option as an alternative to-id
.-use-tls=<value>
Specifies whether gossip over this area should be encrypted with TLS if possible. Must be eithertrue
orfalse
.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.