Manage cluster peering connections on Kubernetes

This usage topic describes how to manage cluster peering connections on Kubernetes deployments.

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 general guidance for managing cluster peering connections, refer to Manage L7 traffic with cluster peering.

Reset a peering connection

To reset the cluster peering connection, you need to generate a new peering token from the cluster where you created the PeeringAcceptor CRD. The only way to create or set a new peering token is to manually adjust the value of the annotation consul.hashicorp.com/peering-version. Creating a new token causes the previous token to expire.

1. In the PeeringAcceptor CRD, add the annotation consul.hashicorp.com/peering-version. If the annotation already exists, update its value to a higher version.

   acceptor.yml

   apiVersion: consul.hashicorp.com/v1alpha1
   kind: PeeringAcceptor
   metadata:
     name: cluster-02
     annotations:
       consul.hashicorp.com/peering-version: "1" ## The peering version you want to set, must be in quotes
   spec:
     peer:
       secret:
         name: "peering-token"
         key: "data"
         backend: "kubernetes"
   

2. After updating PeeringAcceptor, repeat all of the steps to establish a new peering connection.

List all peering connections

In Consul on Kubernetes deployments, you can list all active peering connections in a cluster using the Consul CLI.

1. If necessary, configure your CLI to interact with the Consul cluster.

2. Run the consul peering list CLI command.

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

Read a peering connection

In Consul on Kubernetes deployments, you can get information about individual peering connections between clusters using the Consul CLI.

1. If necessary, configure your CLI to interact with the Consul cluster.

2. Run the consul peering read CLI command.

   $ 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
   

Delete peering connections

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

1. Delete the PeeringDialer resource from the second cluster.

   $ kubectl --context $CLUSTER2_CONTEXT delete --filename dialer.yaml
   

2. Delete the PeeringAcceptor resource from the first cluster.

   $ kubectl --context $CLUSTER1_CONTEXT delete --filename acceptor.yaml
   

To confirm that you deleted your peering connection in cluster-01, query the /health HTTP endpoint:

1. Exec into the server pod for the first cluster.

   $ kubectl exec -it consul-server-0 --context $CLUSTER1_CONTEXT -- /bin/sh
   

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

   $ export CONSUL_HTTP_TOKEN=<INSERT BOOTSTRAP ACL TOKEN>
   

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

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