mirror of https://github.com/hashicorp/consul
69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
---
|
|
layout: commands
|
|
page_title: 'Commands: Peering Generate Token'
|
|
description: |
|
|
The `consul peering generate-token` command creates a peering token that clusters use to establish secure cluster peering connections.
|
|
---
|
|
|
|
# Consul Peering Generate Token
|
|
|
|
Command: `consul peering generate-token`
|
|
|
|
Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/token](/consul/api-docs/peering#generate-a-peering-token)
|
|
|
|
The `peering generate-token` generates a peering token. The token is base 64-encoded string containing the token details.
|
|
This token should be transferred to the other cluster being peered and consumed using [`consul peering establish`](/consul/commands/peering/establish).
|
|
|
|
Generating a token and specifying the same local name associated with a previously-generated token does not affect active connections established with the original token. If the previously-generated token is not actively being used for a peer connection, however, it will become invalid when the new token with the same local name is generated.
|
|
|
|
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| ACL Required |
|
|
| ------------ |
|
|
| `peering:write` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul peering generate-token [options] -name <peer name>`
|
|
|
|
#### Command Options
|
|
|
|
- `-name=<string>` - (Required) Specifies a local name for the cluster that the token is intended for.
|
|
The `name` is only used to identify the connection with the peer.
|
|
Generating a token and specifying the same local name associated with a previously-generated token does not affect active connections established with the original token.
|
|
If the previously-generated token is not actively being used for a peer connection, however, it will become invalid when the new token with the same local name is generated.
|
|
|
|
- `-meta=<string>=<string>` - Specifies key/value pairs to associate with the peering connection token in `-meta="key"="value"` format. You can use the flag multiple times to set multiple metadata fields.
|
|
|
|
- `-server-external-addresses=<string>[,string,...]` - Specifies a comma-separated list of addresses
|
|
to put into the generated token. Addresses are of the form of `{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.
|
|
|
|
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'cli-http-api-partition-options.mdx'
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
## Examples
|
|
|
|
The following example generates a peering token for a cluster called "cluster-02":
|
|
|
|
```shell-session hideClipboard
|
|
$ consul peering generate-token -name cluster-02
|
|
eyJDQSI6bnVs...5Yi0wNzk5NTA1YTRmYjYifQ==
|
|
```
|
|
|
|
### Using a Load Balancer for Consul Servers
|
|
|
|
The following example generates a token for a cluster where servers are proxied by a load balancer:
|
|
|
|
```shell-session hideClipboard
|
|
$ consul peering generate-token -server-external-addresses my-load-balancer-1234567890abcdef.elb.us-east-2.amazonaws.com -name cluster-02
|
|
eyJDQSI6bnVs...5Yi0wNzk5NTA1YTRmYjYifQ==
|
|
```
|