Docs/cluster peering 1.15 updates (#16291)

* initial commit

* initial commit

* Overview updates

* Overview page improvements

* More Overview improvements

* improvements

* Small fixes/updates

* Updates

* Overview updates

* Nav data

* More nav updates

* Fix

* updates

* Updates + tip test

* Directory test

* refining

* Create restructure w/ k8s

* Single usage page

* Technical Specification

* k8s pages

* typo

* L7 traffic management

* Manage connections

* k8s page fix

* Create page tab corrections

* link to k8s

* intentions

* corrections

* Add-on intention descriptions

* adjustments

* Missing </CodeTabs>

* Diagram improvements

* Final diagram update

* Apply suggestions from code review

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Co-authored-by: David Yu <dyu@hashicorp.com>

* diagram name fix

* Fixes

* Updates to index.mdx

* Tech specs page corrections

* Tech specs page rename

* update link to tech specs

* K8s - new pages + tech specs

* k8s - manage peering connections

* k8s L7 traffic management

* Separated establish connection pages

* Directory fixes

* Usage clean up

* k8s docs edits

* Updated nav data

* CodeBlock Component fix

* filename

* CodeBlockConfig removal

* Redirects

* Update k8s filenames

* Reshuffle k8s tech specs for clarity, fmt yaml files

* Update general cluster peering docs, reorder CLI > API > UI, cross link to kubernetes

* Fix config rendering in k8s usage docs, cross link to general usage from k8s docs

* fix legacy link

* update k8s docs

* fix nested list rendering

* redirect fix

* page error

---------

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Co-authored-by: David Yu <dyu@hashicorp.com>
Co-authored-by: Tu Nguyen <im2nguyen@gmail.com>

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

@@ -2,26 +2,34 @@
 layout: docs
 page_title: Cluster Peering Overview
 description: >-
-  Cluster peering establishes communication between independent clusters in Consul, allowing services to interact across datacenters. Learn about the cluster peering process, differences with WAN federation for multi-datacenter deployments, and technical constraints.  
+  Cluster peering establishes communication between independent clusters in Consul, allowing services to interact across datacenters. Learn how cluster peering works, its differences with WAN federation for multi-datacenter deployments, and how to troubleshoot common issues.  
 ---
 
-# Overview
+# Cluster peering overview
 
-You can create peering connections between two or more independent clusters so that services deployed to different partitions or datacenters can communicate. Cluster peering enables connections between different clouds or runtime environments when general interconnectivity between all services in all clusters is not feasible.
+This topic provides an overview of cluster peering, which lets you connect two or more independent Consul clusters so that services deployed to different partitions or datacenters can communicate.
+Cluster peering is enabled in Consul by default. For specific information about cluster peering configuration and usage, refer to following pages.
 
-## Introduction
+## What is cluster peering?
 
-Cluster peering is a process that allows Consul clusters to communicate with each other by connecting two [admin partitions](/docs/enterprise/admin-partitions). Deployments without an Enterprise license can still use cluster peering because every datacenter automatically includes a `default` partition.
+Consul supports cluster peering connections between two [admin partitions](/consul/docs/enterprise/admin-partitions) _in different datacenters_. Deployments without an Enterprise license can still use cluster peering because every datacenter automatically includes a default partition. Meanwhile, admin partitions _in the same datacenter_ do not require cluster peering connections because you can export services between them without generating or exchanging a peering token.
 
-Mesh gateways are required for you to route service mesh traffic between partitions with cluster peering connections. For more information, refer to [mesh gateway requirements](#mesh-gateway-requirements).
+The following diagram describes Consul's cluster peering architecture.
 
-For detailed instructions about creating new cluster peering connections, refer to [Establish cluster peering connections](/docs/connect/cluster-peering/create-manage-peering).
+![Diagram of cluster peering with admin partitions](/img/cluster-peering-diagram.png)
 
-> 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).
+In this diagram, the `default` partition in Consul DC 1 has a cluster peering connection with the `web` partition in Consul DC 2. Enforced by their respective mesh gateways, this cluster peering connection enables `Service B` to communicate with `Service C` as a service upstream.
 
-## Differences between WAN federation and cluster peering
+Cluster peering leverages several components of Consul's architecture to enforce secure communication between services:
 
-WAN federation and cluster peering are different ways to connect Consul deployments through mesh gateways. 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.
+- A _peering token_ contains an embedded secret that securely establishes communication when shared symetrically between datacenters. Sharing this token enables each datacenter's server agents to recognize requests from authorized peers, similar to how the [gossip encryption key secures agent LAN gossip](/consul/docs/security/encryption#gossip-encryption).
+- A _mesh gateway_ encrypts outgoing traffic, decrypts incoming traffic, and directs traffic to healthy services. Consul's service mesh features must be enabled in order to use mesh gateways. Mesh gateways support the specific admin partitions they are deployed on. Refer to [Mesh gateways](/consul/docs/connect/gateways/mesh-gateway) for more information.
+- An _exported service_ communicates with downstreams deployed in other admin partitions. They are explicitly defined in an [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services).
+- A _service intention_ secures [service-to-service communication in a service mesh](/consul/docs/connect/intentions). Intentions enable identity-based access between services by exchanging TLS certificates, which the service's sidecar proxy verifies upon each request.
+
+### Compared with WAN federation
+
+WAN federation and cluster peering are different ways to connect services through mesh gateways so that they can communicate across datacenters. 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.
 
 WAN federation and cluster peering also treat encrypted traffic differently. While mesh gateways between WAN federated datacenters use mTLS to keep data encrypted, mesh gateways between peers terminate mTLS sessions, 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.
 
@@ -39,19 +47,40 @@ Regardless of whether you connect your clusters through WAN federation or cluste
 | Shares key/value stores                            |    ✅     |    ❌     |
 | Can replicate ACL tokens, policies, and roles      |    ✅     |    ❌     |
 
-## Mesh gateway requirements
+## Guidance
+
+The following resources are available to help you use Consul's cluster peering features.
+
+**Tutorials:**
+
+- To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) and Google Kubernetes Engine (GKE) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](/consul/tutorials/developer-mesh/cluster-peering).
+
+**Usage documentation:**
+
+- [Establish cluster peering connections](/consul/docs/connect/cluster-peering/usage/establish-peering)
+- [Manage cluster peering connections](/consul/docs/connect/cluster-peering/usage/manage-connections)
+- [Manage L7 traffic with cluster peering](/consul/docs/connect/cluster-peering/usage/peering-traffic-management)
+
+**Kubernetes-specific documentation:**
+
+- [Cluster peering on Kubernetes technical specifications](/consul/docs/k8s/connect/cluster-peering/tech-specs)
+- [Establish cluster peering connections on Kubernetes](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering)
+- [Manage cluster peering connections on Kubernetes](/consul/docs/k8s/connect/cluster-peering/usage/manage-peering)
+- [Manage L7 traffic with cluster peering on Kubernetes](/consul/docs/k8s/connect/cluster-peering/usage/l7-traffic)
 
-Consider the following requirements for using mesh gateways for cluster peering:
+**Reference documentation:**
 
-- At a minimum, a peered cluster exporting a service must have a mesh gateway registered.
-- For Enterprise, this mesh gateway must also be registered in the same partition as the exported services.
-- To use the `local` mesh gateway mode, there must also be a mesh gateway regsitered in the importing cluster.
+- [Cluster peering technical specifications](/consul/docs/connect/cluster-peering/tech-specs)
+- [HTTP API reference: `/peering/` endpoint](/consul/api-docs/peering)
+- [CLI reference: `peering` command](/consul/commands/peering).
 
-## Technical Constraints
+## Basic troubleshooting
 
-Consider the following technical constraints:
+If you experience errors when using Consul's cluster peering features, refer to the following list of technical constraints.
 
+- Peer names can only contain lowercase characters.
 - Services with node, instance, and check definitions totaling more than 8MB cannot be exported to a peer.
-- Two admin partitions in the same datacenter cannot be peered. You can use [`exported-services`](/docs/connect/config-entries/exported-services#exporting-services-to-peered-clusters) directly instead.
-- 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).
+- Two admin partitions in the same datacenter cannot be peered. Use the [`exported-services` configuration entry](/consul/docs/connect/config-entries/exported-services#exporting-services-to-peered-clusters) instead.
+- To manage intentions that specify services in peered clusters, use [configuration entries](/consul/docs/connect/config-entries/service-intentions). The `consul intention` CLI command is not supported.
+- The Consul UI does not support exporting services between clusters or creating service intentions. Use either the API or the CLI to complete these required steps when establishing new cluster peering connections.
 - Accessing key/value stores across peers is not supported.