open-consul/website/pages/api-docs/operator/area.mdx

418 lines
12 KiB
Plaintext
Raw Normal View History

2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Network Areas - Operator - HTTP API
sidebar_title: Area
2017-04-04 16:33:22 +00:00
description: |-
The /operator/area endpoints expose the network tomography information via
Consul's HTTP API.
---
# Network Areas - Operator HTTP API
<EnterpriseAlert />
2017-07-28 16:28:11 +00:00
The `/operator/area` endpoints provide tools to manage network areas via
2017-04-04 16:33:22 +00:00
Consul's HTTP API.
The network area functionality described here is available only in
[Consul Enterprise](https://www.hashicorp.com/products/consul/) version 0.8.0 and
2017-04-04 16:33:22 +00:00
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](https://learn.hashicorp.com/tutorials/consul/federation-network-areas) for more details.
2017-04-04 16:33:22 +00:00
## Create Network Area
This endpoint creates a new network area and returns its ID if it is created
successfully.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------- | ------------------ |
| `POST` | `/operator/area` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ---------------- |
| `NO` | `none` | `none` | `operator:write` |
2017-04-04 16:33:22 +00:00
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
- `PeerDatacenter` `(string: <required>)` - Specifies the name of the Consul
2017-04-04 16:33:22 +00:00
datacenter that will be joined the Consul servers in the current datacenter to
form the area. Only one area is allowed for each possible `PeerDatacenter`,
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 as `IP`, `IP:port`, `hostname`, or
`hostname: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
2020-04-13 21:24:10 +00:00
[join endpoint](#join-network-area) once the network area is created.
2017-04-04 16:33:22 +00:00
2017-07-06 06:05:22 +00:00
- `UseTLS` `(bool: <optional>)` - Specifies whether gossip over this area should be
encrypted with TLS if possible.
2017-04-04 16:33:22 +00:00
### Sample Payload
```json
{
"PeerDatacenter": "dc2",
2020-04-06 20:27:35 +00:00
"RetryJoin": ["10.1.2.3", "10.1.2.4", "10.1.2.5"],
2017-07-06 06:05:22 +00:00
"UseTLS": false
2017-04-04 16:33:22 +00:00
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/area
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
## List Network Areas
This endpoint lists all network areas.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------- | ------------------ |
| `GET` | `/operator/area` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `YES` | `all` | `none` | `operator:read` |
2017-04-04 16:33:22 +00:00
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/operator/area
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": ["10.1.2.3", "10.1.2.4", "10.1.2.5"]
}
]
```
2017-07-06 06:05:22 +00:00
## Update Network Area
This endpoint updates a network area to the given configuration.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------------- | ------------------ |
| `PUT` | `/operator/area/:uuid` | `application/json` |
2017-07-06 06:05:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-07-06 06:05:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ---------------- |
| `NO` | `none` | `none` | `operator:write` |
2017-07-06 06:05:22 +00:00
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
- `UseTLS` `(bool: <optional>)` - Specifies whether gossip over this area should be
encrypted with TLS if possible.
### Sample Payload
```json
{
"UseTLS": true
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-07-06 06:05:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
2017-07-06 06:05:22 +00:00
```
2017-04-04 16:33:22 +00:00
## List Specific Network Area
This endpoint lists a specific network area.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------------- | ------------------ |
| `GET` | `/operator/area/:uuid` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `YES` | `all` | `none` | `operator:read` |
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": ["10.1.2.3", "10.1.2.4", "10.1.2.5"]
}
]
```
## Delete Network Area
This endpoint deletes a specific network area.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| -------- | ---------------------- | ------------------ |
| `DELETE` | `/operator/area/:uuid` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ---------------- |
| `NO` | `none` | `none` | `operator:write` |
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to delete. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request DELETE \
http://127.0.0.1:8500/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
2017-04-04 16:33:22 +00:00
```
## Join Network Area
This endpoint attempts to join the given Consul servers into a specific network
area.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `PUT` | `/operator/area/:uuid/join` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ---------------- |
| `NO` | `none` | `none` | `operator:write` |
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to join. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Payload
2017-04-04 16:33:22 +00:00
```json
["10.1.2.3", "10.1.2.4", "10.1.2.5"]
```
This can be provided as `IP`, `IP:port`, `hostname`, or `hostname:port`.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/join
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"Address": "10.1.2.3",
"Joined": true,
"Error": ""
},
{
"Address": "10.1.2.4",
"Joined": true,
"Error": ""
},
{
"Address": "10.1.2.5",
"Joined": true,
"Error": ""
}
]
```
- `Address` has the address requested to join.
- `Joined` will be `true` if the Consul server at the given address was
successfully joined into the network area. Otherwise, this will be `false` and
`Error` 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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------------------ | ------------------ |
| `GET` | `/operator/area/:uuid/members` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `operator:read` |
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/members
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"ID": "afc5d95c-1eee-4b46-b85b-0efe4c76dd48",
"Name": "node-2.dc1",
"Addr": "127.0.0.2",
"Port": 8300,
"Datacenter": "dc1",
"Role": "server",
"Build": "0.8.0",
"Protocol": 2,
"Status": "alive",
"RTT": 256478
2020-04-06 20:27:35 +00:00
}
2017-04-04 16:33:22 +00:00
]
```
- `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.
2020-04-09 23:46:54 +00:00
- `Protocol` is the [protocol version](/docs/upgrading#protocol-versions)
2017-04-04 16:33:22 +00:00
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
2020-04-09 23:46:54 +00:00
coordinates](/docs/internals/coordinates).