53 lines
2.0 KiB
Plaintext
53 lines
2.0 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: Peering Establish'
|
|
description: Learn how to use the consul peering establish command to establish a peering connection between Consul clusters.
|
|
---
|
|
|
|
# Consul Peering Establish
|
|
|
|
Command: `consul peering establish`
|
|
|
|
Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/establish](/api-docs/peering#establish-a-peering-connection)
|
|
|
|
The `peering establish` starts a peering connection with the cluster that generated the peering token.
|
|
You can generate cluster peering tokens using the [`consul peering generate-token`](/commands/operator/generate-token) command or the [HTTP API](https://www.consul.io/api-docs/peering#generate-a-peering-token).
|
|
|
|
You can only use a peering token to establish the connection once. If you need to reestablish a peering connection, you must generate a new token.
|
|
|
|
The table below shows this command's [required ACLs](/api-docs#authentication).
|
|
|
|
| ACL Required |
|
|
| ------------ |
|
|
| `peering:write` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul peering establish [options] -name <peer name> -peering-token <token>`
|
|
|
|
#### Command Options
|
|
|
|
- `-name=<string>` - (Required) Specifies a local name for the cluster you are establishing a connection with. The `name` is only used to identify the connection with the peer.
|
|
|
|
- `-peering-token=<string>` - (Required) Specifies the peering token from the cluster that generated the token.
|
|
|
|
- `-meta=<string>=<string>` - Specifies key/value pairs to associate with the peering connection in `-meta="key"="value"` format. You can use the flag multiple times to set multiple metadata fields.
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'http_api_partition_options.mdx'
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
## Examples
|
|
|
|
The following examples establishes a peering connection with a cluster locally referred to as "cluster-01":
|
|
|
|
```shell-session hideClipboard
|
|
$ consul peering establish -name cluster-01 -peering-token eyJDQSI6bnVs...5Yi0wNzk5NTA1YTRmYjYifQ==
|
|
Successfully established peering connection with cluster-01
|
|
```
|
|
|