Network Areas - Operator HTTP API
This feature requires Consul Enterprise(opens in new tab).
The /operator/area
endpoints provide tools to manage network areas via
Consul's HTTP API.
The network area functionality described here is available only in Consul Enterprise version 0.8.0 and later. Network areas 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.
Please check the Network Areas tutorial for more details.
Create Network Area
This endpoint creates a new network area and returns its ID if it is created successfully.
Method | Path | Produces |
---|---|---|
POST | /operator/area | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
NO | none | none | operator:write |
The corresponding CLI command is consul operator area create
.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
JSON Request Body Schema
PeerDatacenter
(string: <required>)
- Specifies 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 possiblePeerDatacenter
, and a datacenter cannot form an area with itself.RetryJoin
(array<string>: nil)
- Specifies a list of Consul servers to attempt to join. Servers can be given asIP
,IP:port
,hostname
, orhostname: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 is not supplied, joining can be done with a call to the join endpoint once the network area is created.UseTLS
(bool: <optional>)
- Specifies whether gossip over this area should be encrypted with TLS if possible.
Sample Payload
Sample Request
Sample Response
List Network Areas
This endpoint lists all network areas.
Method | Path | Produces |
---|---|---|
GET | /operator/area | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
YES | all | none | operator:read |
The corresponding CLI command is consul operator area list
.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
Sample Request
Sample Response
Update Network Area
This endpoint updates a network area to the given configuration.
Method | Path | Produces |
---|---|---|
PUT | /operator/area/:uuid | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
NO | none | none | operator:write |
The corresponding CLI command is consul operator area update
.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
JSON Request Body Schema
UseTLS
(bool: <optional>)
- Specifies whether gossip over this area should be encrypted with TLS if possible.
Sample Payload
Sample Request
List Specific Network Area
This endpoint lists a specific network area.
Method | Path | Produces |
---|---|---|
GET | /operator/area/:uuid | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
YES | all | none | operator:read |
Path Parameters
uuid
(string: <required>)
- Specifies the UUID of the area to list.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
Sample Request
Sample Response
Delete Network Area
This endpoint deletes a specific network area.
Method | Path | Produces |
---|---|---|
DELETE | /operator/area/:uuid | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
NO | none | none | operator:write |
The corresponding CLI command is consul operator area delete
.
Path Parameters
uuid
(string: <required>)
- Specifies the UUID of the area to delete.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
Sample Request
Join Network Area
This endpoint attempts to join the given Consul servers into a specific network area.
Method | Path | Produces |
---|---|---|
PUT | /operator/area/:uuid/join | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
NO | none | none | operator:write |
The corresponding CLI command is consul operator area join
.
Path Parameters
uuid
(string: <required>)
- Specifies the UUID of the area to join.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
Sample Payload
This can be provided as IP
, IP:port
, hostname
, or hostname:port
.
Sample Request
Sample Response
Address
has the address requested to join.Joined
will betrue
if the Consul server at the given address was successfully joined into the network area. Otherwise, this will befalse
andError
will have a human-readable message about why the join didn't succeed.
List Network Area Members
This endpoint provides a listing of the Consul servers present in a specific network area.
Method | Path | Produces |
---|---|---|
GET | /operator/area/:uuid/members | application/json |
The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.
Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
---|---|---|---|
NO | none | none | operator:read |
The corresponding CLI command is consul operator area members
.
Path Parameters
uuid
(string: <required>)
- Specifies the UUID of the area to list.
Query Parameters
dc
(string: "")
- Specifies the datacenter to query. This will default to the datacenter of the agent being queried.
Sample Request
Sample Response
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 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.