mirror of https://github.com/hashicorp/consul
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
353 lines
10 KiB
353 lines
10 KiB
--- |
|
layout: api |
|
page_title: Cluster Peering - HTTP API |
|
description: The /peering endpoints allow for managing cluster peerings. |
|
--- |
|
|
|
# Cluster Peering - HTTP API |
|
|
|
The functionality described here is available only in |
|
[Consul](https://www.hashicorp.com/products/consul/) version 1.13.0 and later. |
|
|
|
## Generate a Peering Token |
|
|
|
This endpoint generates a peering token. |
|
|
|
| Method | Path | Produces | |
|
| ------- | -------------------- | ------------------ | |
|
| `POST` | `/peering/token` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ---------------- | |
|
| `NO` | `none` | `none` | `peering:write` | |
|
|
|
### JSON Request Body Schema |
|
|
|
- `PeerName` `(string: <required>)` - The name assigned to the peer cluster. |
|
The `PeerName` is used to reference the peer cluster in service discovery queries |
|
and configuration entries such as `service-intentions`. This field must be a |
|
valid DNS hostname label. |
|
|
|
@include 'http-api-body-options-partition.mdx' |
|
|
|
- `ServerExternalAddresses` `([]string: <optional>)` - The addresses for the cluster that generates the peering token. Addresses take the form `{host or IP}:port`. |
|
You can specify one or more load balancers or external IPs that route external traffic to this cluster's Consul servers. |
|
|
|
- `Meta` `(map<string|string>: <optional>)` - Specifies KV metadata to associate with |
|
the peering. This parameter is not required and does not directly impact the cluster |
|
peering process. |
|
|
|
### Sample Payload |
|
|
|
```json |
|
{ |
|
"PeerName": "cluster-02", |
|
"Meta": { |
|
"env": "production" |
|
} |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request POST \ |
|
--header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/peering/token |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"PeeringToken": "eyJDQSI6bnVsbCwiU2V..." |
|
} |
|
``` |
|
|
|
## Establish a Peering Connection |
|
|
|
This endpoint establishes a peering connection with a given peering token. |
|
|
|
| Method | Path | Produces | |
|
| ------- | -------------------- | ------------------ | |
|
| `POST` | `/peering/establish` | `application/json` | |
|
|
|
This endpoint returns no data. Success or failure is indicated by the status |
|
code returned. |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ---------------- | |
|
| `NO` | `none` | `none` | `peering:write` | |
|
|
|
### JSON Request Body Schema |
|
|
|
- `PeerName` `(string: <required>)` - The name assigned to the peer cluster. |
|
The `PeerName` is used to reference the peer cluster in service discovery queries |
|
and configuration entries such as `service-intentions`. This field must be a |
|
valid DNS hostname label. |
|
|
|
@include 'http-api-body-options-partition.mdx' |
|
|
|
- `PeeringToken` `(string: <required>)` - The peering token fetched from the |
|
peer cluster. |
|
|
|
- `Meta` `(map<string|string>: <optional>)` - Specifies KV metadata to associate with |
|
the peering. This parameter is not required and does not directly impact the cluster |
|
peering process. |
|
|
|
### Sample Payload |
|
|
|
```json |
|
{ |
|
"PeerName": "cluster-01", |
|
"PeeringToken": "eyJDQSI6bnVsbCwiU2V...", |
|
"Meta": { |
|
"env": "production" |
|
} |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request POST \ |
|
--header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/peering/establish |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{} |
|
``` |
|
|
|
## Read a Peering Connection |
|
|
|
This endpoint returns information about a peering connection for the specified peer name. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ------------------ | ------------------ | |
|
| `GET` | `/peering/:name` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | -------------- | |
|
| `YES` | `consistent` | `none` | `peering:read` | |
|
|
|
### Path Parameters |
|
|
|
- `name` `(string: <required>)` - Specifies the peering to read. |
|
|
|
### Query Parameters |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \ |
|
http://127.0.0.1:8500/v1/peering/cluster-02 |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "462c45e8-018e-f19d-85eb-1fc1bcc2ef12", |
|
"Name": "cluster-02", |
|
"State": "INITIAL", |
|
"PeerID": "e83a315c-027e-bcb1-7c0c-a46650904a05", |
|
"PeerServerName": "server.dc1.consul", |
|
"PeerServerAddresses": [ |
|
"10.0.0.1:8300" |
|
], |
|
"StreamStatus": { |
|
"ImportedServices": [ |
|
"db", |
|
], |
|
"ExportedServices": [ |
|
"backend", |
|
"frontend", |
|
"web" |
|
], |
|
"LastHeartbeat": "2023-12-13T06:31:28.227392Z", |
|
"LastReceive": "2023-12-13T06:31:28.227392Z", |
|
"LastSend": "2023-12-05T11:02:57.528676Z" |
|
}, |
|
"CreateIndex": 89, |
|
"ModifyIndex": 89, |
|
"Remote": { |
|
"Partition": "", |
|
"Datacenter": "east" |
|
} |
|
} |
|
``` |
|
|
|
## Delete a Peering Connection |
|
|
|
Call this endpoint to delete a peering connection. Consul deletes all data imported from the peer in the background. The peering connection is removed after all associated data has been deleted. |
|
Operators can still read the peering connections while the data is being removed. A `DeletedAt` |
|
field will be populated with the timestamp of when the peering was marked for deletion. |
|
|
|
| Method | Path | Produces | |
|
| -------- | ------------------ | -------- | |
|
| `DELETE` | `/peering/:name` | N/A | |
|
|
|
This endpoint returns no data. Success or failure is indicated by the status |
|
code returned. |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ---------------- | |
|
| `NO` | `none` | `none` | `peering:write` | |
|
|
|
### Path Parameters |
|
|
|
- `name` `(string: <required>)` - Specifies the name of the peering to delete. |
|
|
|
### Query Parameters |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request DELETE \ |
|
--header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \ |
|
http://127.0.0.1:8500/v1/peering/cluster-02 |
|
``` |
|
|
|
### Sample Read Output After Deletion Prior to Removal |
|
|
|
```json |
|
{ |
|
"ID": "462c45e8-018e-f19d-85eb-1fc1bcc2ef12", |
|
"Name": "cluster-02", |
|
"State": "TERMINATED", |
|
"PeerID": "e83a315c-027e-bcb1-7c0c-a46650904a05", |
|
"PeerServerName": "server.dc1.consul", |
|
"PeerServerAddresses": [ |
|
"10.0.0.1:8300" |
|
], |
|
"DeletedAt": "2022-12-14T23:00:00Z", |
|
"CreateIndex": 89, |
|
"ModifyIndex": 89 |
|
} |
|
``` |
|
|
|
## List all Peerings |
|
|
|
This endpoint lists all the peerings. |
|
|
|
@include 'http_api_results_filtered_by_acls.mdx' |
|
|
|
| Method | Path | Produces | |
|
| ------ | ------------- | ------------------ | |
|
| `GET` | `/peerings` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | -------------------- | -------------- | |
|
| `YES` | `consistent` | `background refresh` | `peering:read` | |
|
|
|
### Query Parameters |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \ |
|
http://127.0.0.1:8500/v1/peerings |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
[ |
|
{ |
|
"ID": "462c45e8-018e-f19d-85eb-1fc1bcc2ef12", |
|
"Name": "cluster-02", |
|
"State": "ACTIVE", |
|
"Partition": "default", |
|
"PeerID": "e83a315c-027e-bcb1-7c0c-a46650904a05", |
|
"PeerServerName": "server.dc1.consul", |
|
"PeerServerAddresses": [ |
|
"10.0.0.1:8300" |
|
], |
|
"StreamStatus": { |
|
"ImportedServices": [ |
|
"db", |
|
], |
|
"ExportedServices": [ |
|
"backend", |
|
"frontend", |
|
"web" |
|
], |
|
"LastHeartbeat": "2023-12-13T06:31:28.227392Z", |
|
"LastReceive": "2023-12-13T06:31:28.227392Z", |
|
"LastSend": "2023-12-05T11:02:57.528676Z" |
|
}, |
|
"CreateIndex": 89, |
|
"ModifyIndex": 89, |
|
"Remote": { |
|
"Partition": "", |
|
"Datacenter": "east" |
|
} |
|
}, |
|
{ |
|
"ID": "1460ada9-26d2-f30d-3359-2968aa7dc47d", |
|
"Name": "cluster-03", |
|
"State": "INITIAL", |
|
"Partition": "default", |
|
"Meta": { |
|
"env": "production" |
|
}, |
|
"StreamStatus": { |
|
"ImportedServices": null, |
|
"ExportedServices": [ |
|
"backend", |
|
"frontend", |
|
], |
|
"LastHeartbeat": "2023-12-13T06:31:28.227392Z", |
|
"LastReceive": "2023-12-13T06:31:28.227392Z", |
|
"LastSend": "2023-12-05T11:02:57.528676Z" |
|
}, |
|
"CreateIndex": 109, |
|
"ModifyIndex": 119, |
|
"Remote": { |
|
"Partition": "", |
|
"Datacenter": "east" |
|
} |
|
} |
|
] |
|
```
|
|
|