Merge pull request #35580 from JStickler/OSSMDOC-205

OSSMDOC-205: Document configuring federating meshes.

Author: JStickler

modules/ossm-federation-config-meshPeer.adoc

@@ -0,0 +1,126 @@
+////
+This module included in the following assemblies:
+* service_mesh/v2x/ossm-federation.adoc
+////
+
+[id="ossm-federation-joining_{context}"]
+= Joining a federated mesh
+
+You declare the federation between two meshes by creating a `ServiceMeshPeer` resource. The `ServiceMeshPeer` resource defines the federation between two meshes, and you use it to configure discovery for the peer mesh, access to the peer mesh, and certificates used to validate the other mesh’s clients.
+
+Meshes are federated on a one-to-one basis, so each pair of peers requires a pair of `ServiceMeshPeer` resources specifying the federation connection to the other service mesh. For example, federating two meshes named `red` and `green` would require two `ServiceMeshPeer` files.
+
+. On red-mesh-system, create a `ServiceMeshPeer` for the green mesh.
+. On green-mesh-system, create a `ServiceMeshPeer` for the red mesh.
+
+Federating three meshes named `red`, `blue`, and `green` would require six `ServiceMeshPeer` files.
+
+. On red-mesh-system, create a `ServiceMeshPeer` for the green mesh.
+. On red-mesh-system, create a `ServiceMeshPeer` for the blue mesh.
+. On green-mesh-system, create a `ServiceMeshPeer` for the red mesh.
+. On green-mesh-system, create a `ServiceMeshPeer` for the blue mesh.
+. On blue-mesh-system, create a `ServiceMeshPeer` for the red mesh.
+. On blue-mesh-system, create a `ServiceMeshPeer` for the green mesh.
+
+//TODO Insert ServiceMeshPeer diagram here
+
+Configuration in the `ServiceMeshPeer` resource includes the following:
+
+* The address of the other mesh’s ingress gateway, which is used for discovery and service requests.
+* The names of the local ingress and egress gateways that is used for interactions with the specified peer mesh.
+* The client ID used by the other mesh when sending requests to this mesh.
+* The trust domain used by the other mesh.
+* The name of a `ConfigMap` containing a root certificate that is used to validate client certificates in the trust domain used by the other mesh.
+
+In the following example, the administrator for the `red-mesh` is configuring federation with the `green-mesh`.
+
+.Example ServiceMeshPeer resource for red-mesh
+[source,yaml]
+----
+kind: ServiceMeshPeer
+apiVersion: federation.maistra.io/v1
+metadata:
+  name: green-mesh
+  namespace: red-mesh-system
+spec:
+  remote:
+    addresses:
+    - ingress-red-mesh.green-mesh-system.apps.domain.com
+  gateways:
+    ingress:
+      name: ingress-green-mesh
+    egress:
+      name: egress-green-mesh
+  security:
+    trustDomain: green-mesh.local
+    clientID: green-mesh.local/ns/green-mesh-system/sa/egress-red-mesh-service-account
+    certificateChain:
+      kind: ConfigMap
+      name: green-mesh-ca-root-cert
+----
+
+.ServiceMeshPeer configuration parameters
+[options="header"]
+[cols="l, a, a"]
+|===
+|Parameter |Description |Values
+|metadata:
+  name:
+|Name of the peer mesh that this resource is configuring federation with.
+|String
+
+|metadata:
+  namespace:
+|System namespace for this mesh, that is, where the mesh control plane is installed.
+|String
+
+|spec:
+  remote:
+    addresses:
+|List of public addresses of the peer meshes' ingress gateways that are servicing requests from this mesh.
+|
+
+|spec:
+  remote:
+    discoveryPort:
+|The port on which the addresses are handling discovery requests.
+|Defaults to 8188
+
+|spec:
+  remote:
+    servicePort:
+|The port on which the addresses are handling service requests.
+|Defaults to 15443
+
+|spec:
+  gateways:
+    ingress:
+      name:
+|Name of the ingress on this mesh that is servicing requests received from the peer mesh. For example, `ingress-green-mesh`.
+|
+
+|spec:
+  gateways:
+    egress:
+      name:
+|Name of the egress on this mesh that is servicing requests sent to the peer mesh. For example, `egress-green-mesh`.
+|
+
+|spec:
+  security:
+    trustDomain:
+|The trust domain used by the peer mesh.
+|<peerMeshName>.local
+
+|spec:
+  security:
+    clientID:
+|The client ID used by the peer mesh when calling into this mesh.
+|<peerMeshTrustDomain>/ns/<peerMeshSystem>/sa/<peerMeshEgressGatewayName>-service-account
+
+|spec:
+  security:
+    certificateChain:
+|The name of a `ConfigMap` resource containing the root certificate used to validate the client certificate(s) presented to this mesh by the peer mesh.
+|<peerMesh>-ca-root-cert
+|===