Merge pull request #14794 from hashicorp/docs/cluster-peering

docs: Cluster peering 1.14 beta release

website/content/docs/connect/cluster-peering/create-manage-peering.mdx

@@ -4,6 +4,7 @@ page_title: Cluster Peering - Create and Manage Connections
 description: >-
   Generate a peering token to establish communication, export services, and authorize requests for cluster peering connections. Learn how to create, list, read, check, and delete peering connections.
 ---
+<TabProvider>
 
 # Create and Manage Cluster Peering Connections
 
@@ -33,7 +34,7 @@ To begin the cluster peering process, generate a peering token in one of your cl
 Every time you generate a peering token, a single-use establishment secret is embedded in the token. Because regenerating a peering token invalidates the previously generated secret, you must use the most recently created token to establish peering connections.
 
 <Tabs>
-<Tab heading="Consul API">
+<Tab heading="Consul API" group="api">
 
 In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to issue a request for a peering token.
 
@@ -57,7 +58,7 @@ Create a JSON file that contains the first cluster's name and the peering token.
 </CodeBlockConfig>
 </Tab>
 
-<Tab heading="Consul CLI">
+<Tab heading="Consul CLI" group="cli">
 
 In `cluster-01`, use the [`consul peering generate-token` command](/commands/operator/generate-token) to issue a request for a peering token.
 
@@ -70,13 +71,13 @@ Save this value to a file or clipboard to be used in the next step on `cluster-0
 
 </Tab>
 
-<Tab heading="Consul UI">
+<Tab heading="Consul UI" group="ui">
 
 1. In the Consul UI for the datacenter associated with `cluster-01`, click **Peers**.
 1. Click **Add peer connection**.
 1. In the **Generate token** tab, enter `cluster-02` in the **Name of peer** field.
 1. Click the **Generate token** button.
-1. Copy the token before you proceed. Be careful not to lose the token, as you cannot view the token again after leaving this screen. If you lose your token, you must generate a new one.
+1. Copy the token before you proceed. You cannot view it again after leaving this screen. If you lose your token, you must generate a new one.
 
 </Tab>
 </Tabs>
@@ -86,7 +87,7 @@ Save this value to a file or clipboard to be used in the next step on `cluster-0
 Next, use the peering token to establish a secure connection between the clusters.
 
 <Tabs>
-<Tab heading="Consul API">
+<Tab heading="Consul API" group="api">
 
 In one of the client agents in "cluster-02," use `peering_token.json` and the [`/peering/establish` endpoint](/api-docs/peering#establish-a-peering-connection) to establish the peering connection. This endpoint does not generate an output unless there is an error.
 
@@ -94,14 +95,13 @@ In one of the client agents in "cluster-02," use `peering_token.json` and the [`
 $ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish
 ```
 
-When you connect server agents through cluster peering, they peer their default partitions. To establish peering connections for other partitions through server agents, you must add the `Partition` field to `peering_token.json` and specify the partitions you want to peer. For additional configuration information, refer to [Cluster Peering - HTTP API](/api-docs/peering).
+When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. To establish peering connections for other partitions through server agents, you must add the `Partition` field to `peering_token.json` and specify the partitions you want to peer. For additional configuration information, refer to [Cluster Peering - HTTP API](/api-docs/peering).
-
 
 You can dial the `peering/establish` endpoint once per peering token. Peering tokens cannot be reused after being used to establish a connection. If you need to re-establish a connection, you must generate a new peering token.
 
 </Tab>
 
-<Tab heading="Consul CLI">
+<Tab heading="Consul CLI" group="cli">
 
 In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection.
 The commands prints "Successfully established peering connection with cluster-01" after the connection is established.
@@ -120,7 +120,7 @@ If you need to re-establish a connection, you must generate a new peering token.
 
 </Tab>
 
-<Tab heading="Consul UI">
+<Tab heading="Consul UI" group="ui">
 
 1. In the Consul UI for the datacenter associated with `cluster 02`, click **Peers** and then **Add peer connection**.
 1. Click **Establish peering**.
@@ -152,7 +152,7 @@ Services = [
       {
         ## The peer name to reference in config is the one set
         ## during the peering process.
-        PeerName = "cluster-02"
+        Peer = "cluster-02"
       }
     ]
   }
@@ -209,7 +209,7 @@ After you establish a peering connection, you can get a list of all active peeri
 You can list all active peering connections in a cluster.
 
 <Tabs>
-<Tab heading="Consul API">
+<Tab heading="Consul API" group="api">
 
 After you establish a peering connection, [query the `/peerings/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the information as a series of JSON objects:
 
@@ -245,7 +245,7 @@ $  curl http://127.0.0.1:8500/v1/peerings
 ```
 </Tab>
 
-<Tab heading="Consul CLI">
+<Tab heading="Consul CLI" group="cli">
 
 After you establish a peering connection, run the [`consul peering list`](/commands/peering/list) command to get a list of all peering connections.
 For example, the following command requests a list of all peering connections and returns the information in a table:
@@ -259,7 +259,7 @@ cluster-03  PENDING  0              0
   ```
 </Tab>
 
-<Tab heading="Consul UI">
+<Tab heading="Consul UI" group="ui">
 
 In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in a datacenter.
 
@@ -272,7 +272,7 @@ The name that appears in the list is the name of the cluster in a different data
 You can get information about individual peering connections between clusters.
 
 <Tabs>
-<Tab heading="Consul API">
+<Tab heading="Consul API" group="api">
 
 After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02" and returns the info as a JSON object:
 
@@ -294,7 +294,7 @@ $  curl http://127.0.0.1:8500/v1/peering/cluster-02
 ```
 </Tab>
 
-<Tab heading="Consul CLI">
+<Tab heading="Consul CLI" group="cli">
 
 After you establish a peering connection, run the [`consul peering read`](/commands/peering/list) command to get peering information about for a specific cluster.
 For example, the following command requests peering connection information for "cluster-02":
@@ -323,7 +323,7 @@ Modify Index: 89
 ```
 </Tab>
 
-<Tab heading="Consul UI">
+<Tab heading="Consul UI" group="ui">
 
 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.
 </Tab>
@@ -347,7 +347,7 @@ A successful query includes service information in the output.
 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.
 
 <Tabs>
-<Tab heading="Consul API">
+<Tab heading="Consul API" group="api">
 
 In "cluster-01," request the deletion through the [`/peering/ endpoint`](/api-docs/peering#delete-a-peering-connection).
 
@@ -356,7 +356,7 @@ $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02
 ```
 </Tab>
 
-<Tab heading="Consul CLI">
+<Tab heading="Consul CLI" group="cli">
 
 In "cluster-01," request the deletion through the [`consul peering delete`](/commands/peering/list) command.
 
@@ -367,7 +367,7 @@ Successfully submitted peering connection, cluster-02, for deletion
 ```
 </Tab>
 
-<Tab heading="Consul UI">
+<Tab heading="Consul UI" group="ui">
 
 In the Consul UI, click **Peers**. The UI lists peering connections you created for clusters in that datacenter.
 
@@ -375,3 +375,152 @@ Next to the name of the peer, click **More** (three horizontal dots) and then **
 
 </Tab>
 </Tabs>
+
+## L7 traffic management between peers
+
+The following sections describe how to enable L7 traffic management features between peered clusters.
+
+### Service resolvers for redirects and failover
+
+As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures.
+
+<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
+
+```hcl
+Kind           = "service-resolver"
+Name           = "frontend"
+ConnectTimeout = "15s"
+Failover = {
+  "*" = {
+    Targets = [
+      {Peer = "cluster-02"}
+    ]   
+  }
+}
+```
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceResolver
+metadata:
+  name: frontend
+spec:
+  connectTimeout: 15s
+  failover:
+    '*':
+      targets:
+        - peer: 'cluster-02'
+          service: 'frontend'
+          namespace: 'default'
+```
+
+```json
+{
+    "ConnectTimeout": "15s",
+    "Kind": "service-resolver",
+    "Name": "frontend",
+    "Failover": {
+        "*": {
+            "Targets": [
+                {
+                    "Peer": "cluster-02"
+                }
+            ]
+        }
+    },
+    "CreateIndex": 250,
+    "ModifyIndex": 250
+}
+```
+
+</CodeTabs>
+
+### Service splitters and custom routes
+
+The `service-splitter` and `service-router` configuration entry kinds do not support directly targeting a service instance hosted on a peer. To split or route traffic to a service on a peer, you must combine the definition with a `service-resolver` configuration entry that defines the service hosted on the peer as an upstream service. For example, to split traffic evenly between `frontend` services hosted on peers, first define the desired behavior locally:
+
+<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
+
+```hcl
+Kind = "service-splitter"
+Name = "frontend"
+Splits = [
+  {
+    Weight  = 50
+    ## defaults to service with same name as configuration entry ("frontend")
+  },
+  {
+    Weight  = 50
+    Service = "frontend-peer"
+  },
+]
+```
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceSplitter
+metadata:
+  name: frontend
+spec:
+  splits:
+    - weight: 50
+      ## defaults to service with same name as configuration entry ("web")
+    - weight: 50
+      service: frontend-peer
+```
+
+```json
+{
+  "Kind": "service-splitter",
+  "Name": "frontend",
+  "Splits": [
+    {
+      "Weight": 50
+    },
+    {
+      "Weight": 50,
+      "Service": "frontend-peer"
+    }
+  ]
+}
+```
+
+</CodeTabs>
+
+Then, create a local `service-resolver` configuration entry named `frontend-peer` and define a redirect targeting the peer and its service:
+
+<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
+
+```hcl
+Kind           = "service-resolver"
+Name           = "frontend-peer"
+Redirect {
+  Service = frontend
+  Peer = "cluster-02"
+}
+```
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceResolver
+metadata:
+  name: frontend-peer
+spec:
+  redirect:
+    peer: 'cluster-02'
+    service: 'frontend'
+```
+
+```json
+{
+    "Kind": "service-resolver",
+    "Name": "frontend-peer",
+    "Redirect": {
+      "Service": "frontend",
+      "Peer": "cluster-02"
+  }
+}
+```
+
+</CodeTabs>
+</TabProvider>

website/content/docs/connect/cluster-peering/index.mdx

@@ -13,17 +13,20 @@ You can create peering connections between two or more independent clusters so t
 
 ## Overview
 
-Cluster peering allows Consul clusters in different datacenters to communicate with each other. The cluster peering process consists of the following steps:
+Cluster peering is a process that allows Consul clusters to communicate with each other. The cluster peering process consists of the following steps:
+
 1. Create a peering token in one cluster.
 1. Use the peering token to establish peering with a second cluster.
 1. Export services between clusters.
 1. Create intentions to authorize services for peers.
 
-For detailed instructions on setting up cluster peering, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering).
+For detailed instructions on establishing cluster peering connections, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering).
+
+> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs).
 
 ### Differences between WAN federation and cluster peering
 
-WAN federation and cluster peering are different ways to connect clusters. The most important distinction is that WAN federation assumes clusters are owned by the same operators, so it maintains and replicates global states such as ACLs and configuration entries. As a result, WAN federation requires a _primary datacenter_ to serve as an authority for replicated data.
+WAN federation and cluster peering are different ways to connect Consul deployments. WAN federation connects multiple datacenters to make them function as if they were a single cluster, while cluster peering treats each datacenter as a separate cluster. As a result, WAN federation requires a primary datacenter to maintain and replicate global states such as ACLs and configuration entries, but cluster peering does not.
 
 Regardless of whether you connect your clusters through WAN federation or cluster peering, human and machine users can use either method to discover services in other clusters or dial them through the service mesh.
 
@@ -34,14 +37,16 @@ Regardless of whether you connect your clusters through WAN federation or cluste
 | Connects clusters owned by different operators     |    ❌    |    ✅      |
 | Functions without declaring primary datacenter     |    ❌    |    ✅      |
 | Replicates exported services for service discovery |    ❌    |    ✅      |
+| Gossip protocol: Requires LAN gossip only          |    ❌    |    ✅      |
 | Forwards service requests for service discovery    |    ✅     |    ❌     |
 | Shares key/value stores                            |    ✅     |    ❌     |
-| Uses gossip protocol                               |    ✅     |    ❌     |
 
 ## Beta release features and constraints
 
-The cluster peering beta includes the following features and functionality:
+The cluster peering beta release includes the following features and functionality:
 
+- **Consul v1.14 beta only**: Dynamic traffic control with a service resolver config entry can target failover and redirects to service instances in a peered cluster.
+- Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering.
 - Mesh gateways for _service to service traffic_ between clusters are available. For more information on configuring mesh gateways across peers, refer to [Service-to-service Traffic Across Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers).
 - You can generate peering tokens, establish, list, read, and delete peerings, and manage intentions for peering connections with both the API and the UI.
 - You can configure [transparent proxies](/docs/connect/transparent-proxy) for peered services.
@@ -51,9 +56,8 @@ Not all features and functionality are available in the beta release. In particu
 
 - Mesh gateways for _server to server traffic_ are not available.
 - Services with node, instance, and check definitions totaling more than 4MB cannot be exported to a peer.
-- Dynamic routing features such as splits, custom routes, and redirects cannot target services in a peered cluster.
+- The `service-splitter` and `service-router` configuration entry kinds cannot directly target a peer. To split or route traffic to a service instance on a peer, you must supplement your desired dynamic routing definition with a `service-resolver` config entry on the dialing cluster. Refer to [L7 traffic management between peers](/docs/connect/cluster-peering/create-manage-peering#L7-traffic) for more information.
-- Configuring service failover across peers is not supported for service mesh.
-- Consul datacenters that are already federated stay federated. You do not need to migrate WAN federated clusters to cluster peering.
 - The `consul intention` CLI command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions).
 - Accessing key/value stores across peers is not supported.
 - Because non-Enterprise Consul instances are restricted to the `default` namespace, Consul Enterprise instances cannot export services from outside of the `default` namespace to non-Enterprise peers.
+- Cross-cluster mesh gateways are supported in `remote` mode only.

website/content/docs/connect/cluster-peering/k8s.mdx

@@ -18,34 +18,35 @@ The following CRDs are used to create and manage a peering connection:
 - `PeeringAcceptor`: Generates a peering token and accepts an incoming peering connection.
 - `PeeringDialer`: Uses a peering token to make an outbound peering connection with the cluster that generated the token.
 
+As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers.
+
+> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs).
+
 ## Prerequisites
 
 You must implement the following requirements to create and use cluster peering connections with Kubernetes:
-- Consul version 1.13.1 or later
+
+- Consul v1.13.1 or later
 - At least two Kubernetes clusters
 - The installation must be running on Consul on Kubernetes version 0.47.1 or later
 
-### Prepare for install
+### Prepare for installation
 
-1. After provisioning a Kubernetes cluster and setting up your kubeconfig file to manage access to multiple Kubernetes clusters, export the Kubernetes context names for future use with `kubectl`. For more information on how to use kubeconfig and contexts, refer to [Configure access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) on the Kubernetes documentation website. 
+Complete the following procedure after you have provisioned a Kubernetes cluster and set up your kubeconfig file to manage access to multiple Kubernetes clusters. 
+
+1. Use the `kubectl` command to export the Kubernetes context names and then set them to variables for future use. For more information on how to use kubeconfig and contexts, refer to the [Kubernetes docs on configuring access to multiple clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
 
     You can use the following methods to get the context names for your clusters:
   
-    * Issue the `kubectl config current-context` command to get the context for the cluster you are currently in.
+    - Use the `kubectl config current-context` command to get the context for the cluster you are currently in.
-    * Issue the `kubectl config get-contexts` command to get all configured contexts in your kubeconfig file.  
+    - Use the `kubectl config get-contexts` command to get all configured contexts in your kubeconfig file.  
     
     ```shell-session
     $ export CLUSTER1_CONTEXT=<CONTEXT for first Kubernetes cluster>
     $ export CLUSTER2_CONTEXT=<CONTEXT for second Kubernetes cluster>
     ```
 
-1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values. 
+1. To establish cluster peering through Kubernetes, create a `values.yaml` file with the following Helm values.
-   
-    With these values,
-    the servers in each cluster will be exposed over a Kubernetes Load balancer service. This service can be customized
-    using [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice). 
-
-    When generating a peering token from one of the clusters, Consul uses the address(es) of the load balancer in the peering token so that the peering stream goes through the load balancer in front of the servers. For customizing the addresses used in the peering token, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration).
 
     <CodeBlockConfig filename="values.yaml">
 
@@ -71,12 +72,16 @@ You must implement the following requirements to create and use cluster peering
     ```
 
     </CodeBlockConfig>
+
+    These Helm values configure the servers in each cluster so that they expose ports over a Kubernetes load balancer service. For additional configuration options, refer to [`server.exposeService`](/docs/k8s/helm#v-server-exposeservice).
+
+    When generating a peering token from one of the clusters, Consul includes a load balancer address in the token so that the peering stream goes through the load balancer in front of the servers. For additional configuration options, refer to [`global.peering.tokenGeneration`](/docs/k8s/helm#v-global-peering-tokengeneration).
   
 ### Install Consul on Kubernetes
 
-1. Install Consul on Kubernetes on each Kubernetes cluster by applying `values.yaml` using the Helm CLI. 
+Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each cluster.
   
-    1. Install Consul on Kubernetes on `cluster-01`
+  1. In `cluster-01`, run the following commands:
   
       ```shell-session
       $ export HELM_RELEASE_NAME=cluster-01
@@ -85,7 +90,8 @@ You must implement the following requirements to create and use cluster peering
       ```shell-session
     $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER1_CONTEXT
       ```
-    1. Install Consul on Kubernetes on `cluster-02`
+
+  1. In `cluster-02`, run the following commands:
   
       ```shell-session
       $ export HELM_RELEASE_NAME=cluster-02
@@ -95,9 +101,13 @@ You must implement the following requirements to create and use cluster peering
     $ helm install ${HELM_RELEASE_NAME} hashicorp/consul --create-namespace --namespace consul --version "0.47.1" --values values.yaml --kube-context $CLUSTER2_CONTEXT
      ```
 
-## Create a peering token
+## Create a peering connection for Consul on Kubernetes
 
-To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. As part of the peering process, the peer names for each respective cluster within the peering are established by using the `metadata.name` values for the `PeeringAcceptor` and `PeeringDialer` CRDs. 
+To peer Kubernetes clusters running Consul, you need to create a peering token and share it with the other cluster. Complete the following steps to create the peer connection.
+
+### Create a peering token
+
+Peers identify each other using the `metadata.name` values you establish when creating the `PeeringAcceptor` and `PeeringDialer` CRDs.
 
 1. In `cluster-01`, create the `PeeringAcceptor` custom resource.
 
@@ -130,7 +140,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
     $ kubectl --context $CLUSTER1_CONTEXT get secret peering-token --output yaml > peering-token.yaml
     ```
 
-## Establish a peering connection between clusters
+### Establish a peering connection between clusters
 
 1. Apply the peering token to the second cluster.
 
@@ -138,7 +148,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
     $ kubectl --context $CLUSTER2_CONTEXT apply --filename peering-token.yaml
     ```
 
-1. In `cluster-02`, create the `PeeringDialer` custom resource. 
+1. In `cluster-02`, create the `PeeringDialer` custom resource.
 
     <CodeBlockConfig filename="dialer.yaml">
 
@@ -163,9 +173,11 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
     $ kubectl --context $CLUSTER2_CONTEXT apply --filename dialer.yaml 
     ```
 
-## Export services between clusters
+### Export services between clusters
 
-1. For the service in "cluster-02" that you want to export, add the following [annotation](/docs/k8s/annotations-and-labels) to your service's pods.
+The examples described in this section demonstrate how to export a service named `backend`. You should change instances of `backend` in the example code to the name of the service you want to export.
+
+1. For the service in `cluster-02` that you want to export, add the following [annotations](/docs/k8s/annotations-and-labels) to your service's pods. 
 
     <CodeBlockConfig filename="backend.yaml">
 
@@ -189,7 +201,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
     metadata:
       name: backend
     ---
-    # deployment for backend
+    # Deployment for backend
     apiVersion: apps/v1
     kind: Deployment
     metadata:
@@ -243,13 +255,13 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
 
     </CodeBlockConfig>
 
-1. Apply the service file and the `ExportedServices` resource for the second cluster.
+1. Apply the service file and the `ExportedServices` resource to the second cluster.
 
     ```shell-session
     $ kubectl apply --context $CLUSTER2_CONTEXT --filename backend.yaml --filename exportedsvc.yaml
     ```
 
-## Authorize services for peers
+### Authorize services for peers
 
 1. Create service intentions for the second cluster.
 
@@ -278,7 +290,7 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
     $ kubectl --context $CLUSTER2_CONTEXT apply --filename intention.yml
     ```
 
-1. For the services in `cluster-01` that you want to access the "backend," add the following annotations to the service file. To dial the upstream service from an application, ensure that the requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). 
+1. For the services in `cluster-01` that you want to access `backend`, add the following annotations to the service file. To dial the upstream service from an application, ensure that the requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). 
 
     <CodeBlockConfig filename="frontend.yaml">
 
@@ -350,10 +362,11 @@ To peer Kubernetes clusters running Consul, you need to create a peering token a
     $ kubectl --context $CLUSTER1_CONTEXT apply --filename frontend.yaml
     ```
 
-1. Run the following command in `frontend` and check the output to confirm that you peered your clusters successfully.
+1. Run the following command in `frontend` and then check the output to confirm that you peered your clusters successfully.
 
     ```shell-session
     $ kubectl --context $CLUSTER1_CONTEXT exec -it $(kubectl --context $CLUSTER1_CONTEXT get pod -l app=frontend -o name) -- curl localhost:9090
+    
     {
       "name": "frontend",
       "uri": "/",
@@ -401,9 +414,9 @@ $ curl "localhost:8500/v1/health/connect/backend?peer=cluster-02"
 
 ## Recreate or reset a peering connection
 
-To recreate or reset the peering connection, you need to generate a new peering token on the cluster where you created the `PeeringAcceptor` (in this example, `cluster-01`).
+To recreate or reset the peering connection, you need to generate a new peering token from the cluster where you created the `PeeringAcceptor`. 
 
-1. You can do this by creating or updating the annotation `consul.hashicorp.com/peering-version` on the `PeeringAcceptor`. If the annotation already exists, update its value to a version that is higher.
+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.
 
     <CodeBlockConfig filename="acceptor.yml" highlight="6" hideClipboard>
 
@@ -424,6 +437,37 @@ To recreate or reset the peering connection, you need to generate a new peering
 
     </CodeBlockConfig>
 
-1. Once you have done this, repeat the steps in the peering process. This includes saving your peering token so that you can export it to the other cluster. This will re-establish peering with the updated token.
+1. After updating `PeeringAcceptor`, repeat the following steps to create a peering connection:
+      1. [Create a peering token](#create-a-peering-token)
+      1. [Establish a peering connection between clusters](#establish-a-peering-connection-between-clusters)
+      1. [Export services between clusters](#export-services-between-clusters)
+      1. [Authorize services for peers](#authorize-services-for-peers)
+      
+      Your peering connection is re-established with the updated token.
 
-~> **Note:** A new peering token is only generated upon manually setting and updating the value of the annotation `consul.hashicorp.com/peering-version`. Creating a new token will cause the previous token to expire.
+~> **Note:** 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.
+
+## Traffic management between peers
+
+As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers.
+
+To configure automatic service failovers and redirect, edit the `ServiceResolver` CRD so that traffic resolves to a backup service instance on a peer. The following example updates the `ServiceResolver` CRD in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in `cluster-02` when it detects multiple connection failures to the primary instance.
+
+<CodeBlockConfig filename="service-resolver.yaml" hideClipboard>
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceResolver
+metadata:
+  name: frontend
+spec:
+  connectTimeout: 15s
+  failover:
+    '*':
+      targets:
+        - peer: 'cluster-02'
+          service: 'backup'
+          namespace: 'default'
+```
+
+</CodeBlockConfig>

website/content/docs/connect/config-entries/exported-services.mdx

@@ -677,4 +677,4 @@ An ACL token with `service:write` permissions is required for the cluster the qu
 
 Exports are available to all services in the consumer cluster. In the previous example, any service with `write` permissions for the `frontend` partition can read exports.
 
-For additional information, refer to [Health HTTP Endpoint](/api-docs/health).
+For additional information, refer to [Health HTTP Endpoint](/api-docs/health).

website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx

@@ -11,7 +11,7 @@ description: >-
 
 Mesh gateways are required for you to route service mesh traffic between different Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible.
 
-Unlike mesh gateways for datacenters and partitions, mesh gateways for cluster peering decrypt data to HTTP services within the mTLS session. Data must be decrypted in order to evaluate and apply dynamic routing rules at the destination cluster, which reduces coupling between peers.
+Unlike mesh gateways for datacenters and partitions, mesh gateways between peers terminate mTLS sessions to decrypt data to HTTP services and then re-encrypt traffic to send to services. Data must be decrypted in order to evaluate and apply dynamic routing rules at the destination cluster, which reduces coupling between peers.
 
 ## Prerequisites