consul/website/content/commands/peering/establish.mdx

54 lines
2.0 KiB
Markdown

---
layout: commands
page_title: 'Commands: Peering Establish'
description: |
The `consul peering establish` command starts a cluster peering connection with another cluster after they exchange a peering token.
---
# Consul Peering Establish
Command: `consul peering establish`
Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/establish](/consul/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`](/consul/commands/peering/generate-token) command or the [HTTP API](/consul/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](/consul/api-docs/api-structure#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 'cli-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
```