Backport of docs(peering): peering GA ACL updates into release/1.14.x (…

…#15476)

This pull request was automerged via backport-assistant

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

@@ -198,6 +198,19 @@ Then, add the configuration entry to your cluster.
 $ consul config write peering-intentions.hcl
 ```
 
+### Authorize Service Reads with ACLs
+
+If ACLs are enabled on a Consul cluster, sidecar proxies that access exported services as an upstream must have an ACL token that grants read access. 
+Read access to all imported services is granted using either of the following rules associated with an ACL token:
+- `service:write` permissions for any service in the sidecar's partition.
+- `service:read` and `node:read` for all services and nodes, respectively, in sidecar's namespace and partition.
+For Consul Enterprise, access is granted to all imported services in the service's partition.
+These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities). 
+
+Example rule files can be found in [Reading Servers](/docs/connect/config-entries/exported-services#reading-services) in the `exported-services` config entry documentation.
+
+Refer to [ACLs System Overview](/docs/security/acl) for more information on ACLs and their setup.
+
 ## Manage peering connections
 
 After you establish a peering connection, you can get a list of all active peering connections, read a specific peering connection's information, check peering connection health, and delete peering connections.

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

@@ -40,6 +40,7 @@ Regardless of whether you connect your clusters through WAN federation or cluste
 | Gossip protocol: Requires LAN gossip only          |    ❌    |    ✅      |
 | Forwards service requests for service discovery    |    ✅     |    ❌     |
 | Shares key/value stores                            |    ✅     |    ❌     |
+| Can replicate ACL tokens, policies, and roles      |    ✅     |    ❌     |
 
 ## Important Cluster Peering Constraints
 

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

@@ -661,20 +661,236 @@ The following example queries the `finance` peer for the imported `payments` ser
 ```shell-session
 $ curl 'localhost:8500/v1/health/service/payments?peer=finance'
 ```
+An ACL token with either of the following permissions is required in the cluster where the query is made: 
+- `service:write` permissions for any service.
+- `service:read` and `node:read` for all services and nodes, respectively.
+
+If the call in the previous example is made from a service named `web`, then the request requires either:
+- A token with `service:write` permissions to `web`.
+- A token with `service:read` and `node:read` to all names in the datacenter.
+
+<CodeTabs heading="Example ACL rules for reading imported services in Consul OSS">
+
+```hcl
+service "web" {
+    policy = "write"
+}
+
+# OR
+
+service_prefix "" {
+    policy = "read"
+}
+node_prefix "" {
+    policy = "read"
+}
+```
+
+```json
+{
+  "service": {
+    "web": {
+      "policy": "write"
+    }
+  }
+}
+
+## OR 
+
+{
+  "service_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "node_prefix": {
+    "": {
+      "policy": "read"
+    }
+  }
+}
+
+```
+
+</CodeTabs>
+
 </Tab>
 
-<Tab heading="Consul Enterprise">
+<Tab heading="Consul Enterprise (Partitions)">
 
 The following example queries the `finance` partition for the imported `payments` service:
 
 ```shell-session
 $ curl 'localhost:8500/v1/health/service/payments?partition=finance'
 ```
+
+An ACL token with either of the following permissions is required in the cluster where the query is made: 
+- `service:write` permissions for any service in the partition where the query is made.
+- `service:read` and `node:read` for all services and nodes, respectively, in any namespace and the exact partition where the query is made.
+
+If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request requires either:
+- A token with `service:write` permissions to `web` in the `frontend` partition.
+- A token with `service:read` and `node:read` to all names in the `frontend` partition, for any namespace.
+
+<CodeTabs heading="Example ACL rules for reading imported services from a partition in Consul Enterprise">
+
+```hcl
+partition "frontend" {
+	namespace "dev" { # This could be any namespace
+		service "web" {
+			policy = "write"
+		}
+	}
+}
+
+# OR
+
+partition "frontend" {
+	namespace "dev" { # This could be any namespace
+		service_prefix "" {
+			policy = "read"
+		}
+		node_prefix "" {
+			policy = "read"
+		}
+	}
+}
+```
+
+```json
+{
+  "partition": {
+    "frontend": {
+	  "namespace": {
+        ## The following could be any namespace
+        "dev": {
+		  "service": {
+            "web": {
+			  "policy": "write"
+            }
+          }
+		}
+      }
+	}
+  }
+}
+
+## OR 
+
+{
+  "partition": {
+    "frontend": {
+	  "namespace": {
+        ## The following could be any namespace
+        "dev": {
+		  "service_prefix": {
+            "": {
+              "policy": "read"
+            }
+          },
+          "node_prefix": {
+            "": {
+              "policy": "read"
+            }
+          }
+		}
+      }
+	}
+  }
+}
+```
+
+</CodeTabs>
+
 </Tab>
-</Tabs>
 
-An ACL token with `service:write` permissions is required for the cluster the query is made from. If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request requires a token with `write` permissions to `web` in the `frontend` partition.
+<Tab heading="Consul Enterprise (Peers)">
+
+The following example queries the `finance` peer for the imported `payments` service:
+
+```shell-session
+$ curl 'localhost:8500/v1/health/service/payments?peer=finance'
+```
+
+An ACL token with either of the following permissions is required in the cluster where the query is made: 
+- `service:write` permissions for any service in the partition where the query is made.
+- `service:read` and `node:read` for all services and nodes, respectively, in any namespace and the exact partition where the query is made.
+
+If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request requires either:
+- A token with `service:write` permissions to `web` in the `frontend` partition.
+- A token with `service:read` and `node:read` to all names in the `frontend` partition, for any namespace.
 
-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.
+<CodeTabs heading="Example ACL rules for reading imported services from a peer in Consul Enterprise">
+
+```hcl
+partition "frontend" {
+	namespace "dev" { # This could be any namespace
+		service "web" {
+			policy = "write"
+		}
+	}
+}
+
+# OR
+
+partition "frontend" {
+	namespace "dev" { # This could be any namespace
+		service_prefix "" {
+			policy = "read"
+		}
+		node_prefix "" {
+			policy = "read"
+		}
+	}
+}
+```
+
+```json
+{
+  "partition": {
+    "frontend": {
+	  "namespace": {
+        ## The following could be any namespace
+        "dev": {
+		  "service": {
+            "web": {
+			  "policy": "write"
+            }
+          }
+		}
+      }
+	}
+  }
+}
+
+## OR 
+
+{
+  "partition": {
+    "frontend": {
+	  "namespace": {
+        ## The following could be any namespace
+        "dev": {
+		  "service_prefix": {
+            "": {
+              "policy": "read"
+            }
+          },
+          "node_prefix": {
+            "": {
+              "policy": "read"
+            }
+          }
+		}
+      }
+	}
+  }
+}
+```
+
+</CodeTabs>
+
+</Tab>
+</Tabs>
 
 For additional information, refer to [Health HTTP Endpoint](/api-docs/health).

website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx

@@ -1,11 +1,11 @@
 ---
 layout: docs
-page_title: Mesh Gateways for Peering Control Plane Traffic
+page_title: Enabling Peering Control Plane Traffic
 description: >-
   Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how to enable traffic across clusters in different datacenters or admin partitions that have an established peering connection.
 ---
 
-# Mesh Gateways for Peering Control Plane Traffic
+# Enabling Peering Control Plane Traffic
 
 In addition to [service-to-service traffic routing](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers), mesh gateways can optionally be used to route control-plane traffic between peers.
 This includes the initial secret handshake and the bi-directional stream replicating peering data.
@@ -38,8 +38,55 @@ For Consul Enterprise clusters, mesh gateways must be registered in the "default
 
 ### ACL configuration
 
-- If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the "default" Enterprise admin partition or OSS datacenter to the gateway's service definition. 
-These permissions authorize the token to route communications for other Consul service mesh services.
+<Tabs>
+<Tab heading="Consul OSS">
+
+In addition to the [ACL Configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings. 
+This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered datacenter.
+
+<CodeTabs heading="Example ACL rules for Mesh Gateway Peering Control Plane Traffic in Consul OSS">
+
+```hcl
+peering = "read"
+```
+
+```json
+{
+  "peering": "read"
+}
+```
+
+</CodeTabs>
+
+</Tab>
+
+<Tab heading="Consul Enterprise">
+
+In addition to the [ACL Configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings in all partitions. 
+This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered partition.
+
+<CodeTabs heading="Example ACL rules for Mesh Gateway Peering Control Plane Traffic in Consul Enterprise">
+
+```hcl
+partition_prefix "" {
+	peering = "read"
+}
+```
+
+```json
+{
+  "partition_prefix": {
+    "": {
+	  "peering": "read"
+	}
+  }
+}
+```
+
+</CodeTabs>
+
+</Tab>
+</Tabs>
 
 ### Modes
 

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

@@ -1,11 +1,11 @@
 ---
 layout: docs
-page_title: Mesh Gateways between Admin Partitions
+page_title: Enabling Service-to-service Traffic Across Admin Partitions
 description: >-
   Mesh gateways are specialized proxies that route data between services that cannot communicate directly with upstreams. Learn how to enable service-to-service traffic across admin partitions and review example configuration entries.
 ---
 
-# Mesh Gateways between Admin Partitions
+# Enabling Service-to-service Traffic Across Admin Partitions
 
 -> **Consul Enterprise 1.11.0+:** Admin partitions are supported in Consul Enterprise versions 1.11.0 and newer.
 

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

@@ -1,11 +1,11 @@
 ---
 layout: docs
-page_title: Mesh Gateways between Peered Clusters
+page_title: Enabling Service-to-service Traffic Across Peered Clusters
 description: >-
   Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how to enable service-to-service traffic across clusters in different datacenters or admin partitions that have an established peering connection.
 ---
 
-# Mesh Gateways between Peered Clusters
+# Enabling Service-to-service Traffic Across Peered Clusters
 
 Mesh gateways are required for you to route service mesh traffic between peered Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible.
 
@@ -47,7 +47,11 @@ Alternatively, you can also use the CLI to spin up and register a gateway in Con
 
 ### ACL configuration
 
-- If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the Enterprise admin partition or OSS datacenter to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services.
+If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the Enterprise admin partition or OSS datacenter to the gateway's service definition. 
+These permissions authorize the token to route communications for other Consul service mesh services.
+
+You must also grant `mesh:write` to mesh gateways routing peering traffic in the data plane.
+This permission allows a leaf certificate to be issued for mesh gateways to terminate TLS sessions for HTTP requests.
 
 ### Modes
 

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

@@ -1,11 +1,11 @@
 ---
 layout: docs
-page_title: Mesh Gateways between WAN-Federated Datacenters
+page_title: Enabling Service-to-service Traffic Across WAN Federated Datacenters
 description: >-
   Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how to enable service-to-service traffic across wan-federated datacenters and review example configuration entries.
 ---
 
-# Mesh Gateways between WAN-Federated Datacenters
+# Enabling Service-to-service Traffic Across WAN Federated Datacenters
 
 -> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.