Add federated services docs

linkerd.io/content/2-edge/features/multicluster.md

@@ -39,8 +39,8 @@ splitting](../traffic-split/) or [dynamic request routing](../request-routing/)
 to allow local services to access the *Foo* service as if it were on the local
 cluster.
 
-Linkerd supports two basic forms of multi-cluster communication: hierarchical
-and flat.
+Linkerd supports three basic forms of multi-cluster communication: hierarchical,
+flat, and federated.
 
 ![Architectural diagram comparing hierarchical and flat network modes](/docs/images/multicluster/flat-network.png)
 
@@ -65,11 +65,18 @@ several advantages:
 * Better multi-cluster authorization policies, as workload identity
   is preserved across cluster boundaries.
 
-Hierarchical (gateway-based) and flat (direct pod-to-pod) modes can be combined,
-and pod-to-pod mode can be enabled for specific services by using the
-`remote-discovery` value for the label selector used to export services to other
-clusters. See the [pod-to-pod multicluster
-communication](../../tasks/pod-to-pod-multicluster/) guide and the
+### Federated services
+
+A federated service is a union of services with the same name and namespace
+in multiple different clusters. Meshed clients that send traffic to a federated
+service will have that traffic distributed across all replicas of services in
+the federated service across clusters. Federated services use the *flat
+networking* model and do not use a gateway intermediary.
+
+These modes can be combined, with each specific services by using the mode that
+is most appropriate. See the
+[pod-to-pod multicluster communication](../../tasks/pod-to-pod-multicluster/)
+guide, the [federated services](../../tasks/federated-services/) guide, and the
 [multi-cluster reference](../../reference/multicluster/) for more.
 
 ## Headless services
@@ -110,14 +117,17 @@ exported as a headless service, the hosts backing the service need to be named
 Deployment would not be supported, since they do not allow for arbitrary
 hostnames in the pod spec).
 
+Note that headless services can *not* be part of a federated service.
+
 Ready to get started? See the [getting started with multi-cluster
 guide](../../tasks/multicluster/) for a walkthrough.
 
 ## Further reading
 
-* [Multi-cluster installation instructions](../../tasks/installing-multicluster/).
+* [Multi-cluster installation instructions](../../tasks/installing-multicluster/)
 * [Pod-to-pod multicluster communication](../../tasks/pod-to-pod-multicluster/)
-* [Multi-cluster communication with StatefulSets](../../tasks/multicluster-using-statefulsets/).
+* [Multi-cluster communication with StatefulSets](../../tasks/multicluster-using-statefulsets/)
+* [Federated services](../../tasks/federated-services/)
 * [Architecting for multi-cluster
   Kubernetes](/2020/02/17/architecting-for-multicluster-kubernetes/), a blog
   post explaining some of the design rationale behind Linkerd's multi-cluster

linkerd.io/content/2-edge/reference/multicluster.md

@@ -5,14 +5,16 @@ description: Multi-cluster communication
 
 Linkerd's [multi-cluster functionality](../../features/multicluster/) allows
 pods to connect to Kubernetes services across cluster boundaries in a way that
-is secure and fully transparent to the application. As of Linkerd 2.14, this
-feature supports two modes: hierarchical (using an gateway) and flat (without a
-gateway):
+is secure and fully transparent to the application. This feature supports three
+modes: hierarchical (using an gateway), flat (without a gateway), and federated.
 
 * **Flat mode** requires that all pods on the source cluster be able to directly
   connect to pods on the destination cluster.
 * **Hierarchical mode** only requires that the gateway IP of the destination
   cluster be reachable by pods on the source cluster.
+* **Federated mode** has the same requirements as flat mode but allows a service
+  deployed to multiple clusters to be treated as a single cluster agnostic
+  service.
 
 These modes can be mixed and matched.
 
@@ -66,3 +68,26 @@ together, a Kubernetes `Secret` is created in the control plane's namespace with
 a kubeconfig file that allows an API client to be configured. The kubeconfig
 file uses RBAC to provide the "principle of least privilege", ensuring the
 *destination service* may only access only the resources it needs.
+
+## Federated Services
+
+Federated services take this a step farther by allowing a service which is
+deployed to multiple clusters to be joined into a single union service.
+
+The service mirror controller will look for all services in all linked clusters
+which match a label selector (`mirror.linkerd.io/federated=member` by default)
+and create a federated service called `<svc name>-federated` which will act as
+a union of all those services with that name. For example, all traffic sent to
+the `store-web-federated` federated service will be load balanced over all
+replicas of all services named `store-web` in all linked clusters.
+
+The concept of "namespace sameness" applies, which means that the federated
+service will be created in the same namespace as the individual services and
+services can only join a federated service in the same namespace.
+
+Since Linkerd's *destination service* uses "remote-discovery" to discover the
+endpoints of a federated service, all of the requirements for flat mode also
+apply to federated services: the clusters must be on a flat network where pods
+in one cluster can connect to pods in the others, the clusters must have the
+same trust root, and any clients connecting to the federated service must be
+meshed.