Skip to content

Commit

Permalink
Manage connections
Browse files Browse the repository at this point in the history
  • Loading branch information
@boruszak
boruszak committed Feb 16, 2023
1 parent 258fbc9 commit 8524b8d
Showing 1 changed file with 204 additions and 8 deletions.
212 changes: 204 additions & 8 deletions website/content/docs/connect/cluster-peering/usage/manage-connections.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,227 @@
layout: docs
page_title: Manage Cluster Peering Connections
description: >-
Learn how to list, read, and delete cluster peering connections using Consul. You can use the HTTP API, the CLI, the Consul UI, or Kubernetes to manage cluster peering connections.
---

# Manage Cluster Peering Connections
# Manage cluster peering connections

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.
This usage topic describes how to manage cluster peering connections using the HTTP API, Consul CLI, Consul UI, and Kubernetes.

This page describes how to use the Consul UI to manage cluster peering connections. To manage cluster peering through the HTTP API, refer to the [`/peering` endpoint reference](/consul/api-docs/peering). If you prefer to use the command line, refer to [`peering` CLI command reference](/consul/commands/peering).
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.

## List all peering connections

You can list all active peering connections in a cluster.

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.
<Tabs>

<Tab heading="HTTP API" group="api">

An API request to list peering connections takes the following form:

```shell-session
$ 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](/consul/api-docs/peering#list-all-peerings).

</Tab>

<Tab heading="Consul CLI" group="cli">

```shell-session
$ 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](/consul/commands/peering/list).

</Tab>

<Tab heading="Consul UI" group="ui">

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.

</Tab>

<Tab heading="Kubernetes" group="k8s">

To read a cluster peering connection using Kubernetes, we recommend using the Consul CLI.

1. If necessary, [configure your CLI to interact with the Consul cluster](/consul/tutorials/get-started-kubernetes/kubernetes-gs-deploy#configure-your-cli-to-interact-with-consul-cluster).

1. Run the [`consul peering list` CLI command](/consul/commands/peering/list).

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

</Tab>
</Tabs>

## Read a peering connection

You can get information about individual peering connections between clusters.

In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter. Click the name of a peered cluster to view additional details about the peering connection.
<Tabs>

<Tab heading="HTTP API" group="api">

```shell-session
$ 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](/consul/api-docs/peering#read-a-peering-connection).

</Tab>

<Tab heading="Consul CLI" group="cli">

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

```shell-session
$ 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](/consul/commands/peering/read).

</Tab>

<Tab heading="Consul UI" group="ui">

1. In the Consul UI, click **Peers**.

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

</Tab>

<Tab heading="Kubernetes" group="k8s">

To read a cluster peering connection using Kubernetes, we recommend using the Consul CLI.

1. If necessary, [configure your CLI to interact with the Consul cluster](/consul/tutorials/get-started-kubernetes/kubernetes-gs-deploy#configure-your-cli-to-interact-with-consul-cluster).

1. Run the [`consul peering read` CLI command](/consul/commands/peering/read).

```shell-session
$ 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
```

</Tab>
</Tabs>

## 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.

In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter.
<Tabs>
<Tab heading="HTTP API" group="api">

```shell-session
$ 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](/consul/api-docs/peering/consul/api-docs/peering#delete-a-peering-connection).
</Tab>

<Tab heading="Consul CLI" group="cli">

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

```shell-session
$ 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](/consul/commands/peering/delete).

</Tab>

<Tab heading="Consul UI" group="ui">

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

</Tab>

<Tab heading="Kubernetes" group="k8s">

To end a peering connection in Kubernetes deployments, delete both the `PeeringAcceptor` and `PeeringDialer` resources.

1. Delete the `PeeringDialer` resource from the second cluster.

```shell-session
$ kubectl --context $CLUSTER2_CONTEXT delete --filename dialer.yaml
```

1. Delete the `PeeringAcceptor` resource from the first cluster.

```shell-session
$ kubectl --context $CLUSTER1_CONTEXT delete --filename acceptor.yaml
````
To confirm that you deleted your peering connection in `cluster-01`, query the the `/health` HTTP endpoint:
1. Exec into the server pod for the first cluster.
```shell-session
$ kubectl exec -it consul-server-0 --context $CLUSTER1_CONTEXT -- /bin/sh
```

1. If you've enabled ACLs, export an ACL token to access the `/health` HTP endpoint for services. The bootstrap token may be used if an ACL token is not already provisioned.

```shell-session
$ export CONSUL_HTTP_TOKEN=<INSERT BOOTSTRAP ACL TOKEN>
```

1. Query the the `/health` HTTP endpoint. Peered services with deleted connections should no longe appear.

```shell-session
$ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02"
```

Next to the name of the peer, click **More** (three horizontal dots) and then **Delete**. Click **Delete** to confirm and remove the peering connection.
</Tab>
</Tabs>

0 comments on commit 8524b8d

Please sign in to comment.