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.

  1. $ consul peering list
  2. Name        State    Imported Svcs  Exported Svcs  Meta
  3. cluster-02  ACTIVE   0              2              env=production
  4. 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:

  1. $ 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.

In the Consul UI, click Peers.

The UI lists peering connections you created for clusters in a datacenter. The name that appears in the list is the name of the cluster in a different datacenter with an established peering connection.

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”:

  1. $ consul peering read -name cluster-02
  2. Name:         cluster-02
  3. ID:           3b001063-8079-b1a6-764c-738af5a39a97
  4. State:        ACTIVE
  5. Meta:
  6.     env=production
  8. Peer ID:               e83a315c-027e-bcb1-7c0c-a46650904a05
  9. Peer Server Name:      server.dc1.consul
  10. Peer CA Pems:          0
  11. Peer Server Addresses:
  12.     10.0.0.1:8300
  14. Imported Services: 0
  15. Exported Services: 2
  17. Create Index: 89
  18. Modify Index: 89

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

  1. $ 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.

  1. In the Consul UI, click Peers.

  2. Click the name of a peered cluster to view additional details about the peering connection.

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”:

  1. $ consul peering delete -name cluster-02
  2. 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.

  1. $ 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.

  1. In the Consul UI, click Peers. The UI lists peering connections you created for clusters in that datacenter.
  2. Next to the name of the peer, click More (three horizontal dots) and then Delete.
  3. Click Delete to confirm and remove the peering connection.