From e72dd6254a04fc76109edf0135ba8e4e9d6da88c Mon Sep 17 00:00:00 2001
From: Nitya Dhanushkodi <nitya@hashicorp.com>
Date: Thu, 24 Nov 2022 10:02:47 -0800
Subject: [PATCH] update docs with mesh and proxydefaults config (#15526)

---
 .../docs/connect/cluster-peering/k8s.mdx      | 77 ++++++++++++++++++-
 1 file changed, 76 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx
index a65ea0193..096605339 100644
--- a/website/content/docs/connect/cluster-peering/k8s.mdx
+++ b/website/content/docs/connect/cluster-peering/k8s.mdx
@@ -97,7 +97,45 @@ Install Consul on Kubernetes by using the CLI to apply `values.yaml` to each clu
 
 ## 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. Complete the following steps to create the peer connection.
+To peer Kubernetes clusters running Consul, you need to create a peering token on one cluster (`cluster-01`) and share
+it with the other cluster (`cluster-02`). The generated peering token from `cluster-01` will include the addresses of
+the servers for that cluster. The servers for `cluster-02` will use that information to dial the servers in
+`cluster-01`. Complete the following steps to create the peer connection.
+
+### Using mesh gateways for the peering connection
+If the servers in `cluster-01` are not directly routable from the dialing cluster `cluster-02`, then you'll need to set up peering through mesh gateways.
+
+1. In `cluster-01` apply the `Mesh` custom resource so the generated token will have the mesh gateway addresses which will be routable from the other cluster.
+
+    <CodeBlockConfig filename="mesh.yaml">
+
+    ```yaml
+    apiVersion: consul.hashicorp.com/v1alpha1
+    kind: Mesh
+    metadata:
+      name: mesh
+    spec:
+      peering:
+        peerThroughMeshGateways: true
+    ```
+
+    </CodeBlockConfig>
+
+1. In `cluster-02` apply the `Mesh` custom resource so that the servers for `cluster-02` will use their local mesh gateway to dial the servers for `cluster-01`.
+
+    <CodeBlockConfig filename="mesh.yaml">
+
+    ```yaml
+    apiVersion: consul.hashicorp.com/v1alpha1
+    kind: Mesh
+    metadata:
+      name: mesh
+    spec:
+      peering:
+        peerThroughMeshGateways: true
+    ```
+
+    </CodeBlockConfig>
 
 ### Create a peering token
 
@@ -167,6 +205,43 @@ Peers identify each other using the `metadata.name` values you establish when cr
     $ kubectl --context $CLUSTER2_CONTEXT apply --filename dialer.yaml
     ```
 
+### Configure the mesh gateway mode for traffic between services
+Mesh gateways are required for service-to-service traffic between peered clusters. By default, this will mean that a
+service dialing another service in a remote peer will dial the remote mesh gateway to reach that service. If you would
+like to configure the mesh gateway mode such that this traffic always leaves through the local mesh gateway, you can use the `ProxyDefaults` CRD.
+
+1. In `cluster-01` apply the following `ProxyDefaults` CRD to configure the mesh gateway mode.
+
+    <CodeBlockConfig filename="proxydefaults.yaml">
+
+    ```yaml
+    apiVersion: consul.hashicorp.com/v1alpha1
+    kind: ProxyDefaults
+    metadata:
+      name: global
+    spec:
+      meshGateway:
+        mode: local
+    ```
+
+    </CodeBlockConfig>
+
+1. In `cluster-02` apply the following `ProxyDefaults` CRD to configure the mesh gateway mode.
+
+    <CodeBlockConfig filename="proxydefaults.yaml">
+
+    ```yaml
+    apiVersion: consul.hashicorp.com/v1alpha1
+    kind: ProxyDefaults
+    metadata:
+      name: global
+    spec:
+      meshGateway:
+        mode: local
+    ```
+
+    </CodeBlockConfig>
+
 ### Export services between clusters
 
 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.