Manage cluster peering connections

This usage topic describes how to manage cluster peering connections using the CLI, the HTTP API, and the UI.

After you establish a cluster peering connection, you can get a list of all active peering connections, read a specific peering connection's information, and delete peering connections.

For Kubernetes-specific guidance for managing cluster peering connections, refer to Manage cluster peering connections on Kubernetes.

List all peering connections

You can list all active peering connections in a cluster.

$ consul peering list
Name        State    Imported Svcs  Exported Svcs  Meta
cluster-02  ACTIVE   0              2              env=production
cluster-03  PENDING  0              0

For more information, including optional flags and parameters, refer to the consul peering list CLI command reference.

The following example shows how to format an API request to list peering connections:

$ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" http://127.0.0.1:8500/v1/peerings

For more information, including optional parameters and sample responses, refer to the /peering endpoint reference.

Read a peering connection

You can get information about individual peering connections between clusters.

The following example outputs information about a peering connection locally referred to as "cluster-02":

$ consul peering read -name cluster-02
Name:         cluster-02
ID:           3b001063-8079-b1a6-764c-738af5a39a97
State:        ACTIVE
Meta:
    env=production

Peer ID:               e83a315c-027e-bcb1-7c0c-a46650904a05
Peer Server Name:      server.dc1.consul
Peer CA Pems:          0
Peer Server Addresses:
    10.0.0.1:8300

Imported Services: 0
Exported Services: 2

Create Index: 89
Modify Index: 89

For more information, including optional flags and parameters, refer to the consul peering read CLI command reference.

$ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" http://127.0.0.1:8500/v1/peering/cluster-02

For more information, including optional parameters and sample responses, refer to the /peering endpoint reference.

Delete peering connections

You can disconnect the peered clusters by deleting their connection. Deleting a peering connection stops data replication to the peer and deletes imported data, including services and CA certificates.

The following examples deletes a peering connection to a cluster locally referred to as "cluster-02":

$ consul peering delete -name cluster-02
Successfully submitted peering connection, cluster-02, for deletion

For more information, including optional flags and parameters, refer to the consul peering delete CLI command reference.

$ curl --request DELETE --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" http://127.0.0.1:8500/v1/peering/cluster-02

This endpoint does not return a response. For more information, including optional parameters, refer to the /peering endpoint reference.