Consul Peering Establish
Command: consul peering establish
Corresponding HTTP API Endpoint: [POST] /v1/peering/establish
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
command or the HTTP API.
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.
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. Thename
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
-partition=<string>
- Specifies the partition to query. If not provided, the partition will be inferred from the request's ACL token, or will default to thedefault
partition. Partitions are a Consul Enterprise feature added in v1.11.0.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_HTTP_TOKEN
environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.-token-file=<value>
- File containing the ACL token to use in the request instead of one specified via the-token
argument orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
Examples
The following examples establishes a peering connection with a cluster locally referred to as "cluster-01":