////
This module included in the following assemblies:
* service_mesh/v2x/ossm-federation.adoc
////

:_mod-docs-content-type: CONCEPT
[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.

image::ossm-federated-mesh.png[Service Mesh federated mesh peers illustration]

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.

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 {SMProductShortName} 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:
      kind: ConfigMap
      name:
|The kind (for example, ConfigMap) and name of a resource containing the root certificate used to validate the client and server certificate(s) presented to this mesh by the peer mesh.
The key of the config map entry containing the certificate should be `root-cert.pem`.
|kind: ConfigMap
name: <peerMesh>-ca-root-cert
|===
