DOCSP-24930: update multi-cluster overview based on PM feedback (#1039)

Author: jwilliams-mongo

conf.py

@@ -186,8 +186,9 @@
     '.. |mongod| replace:: :binary:`~bin.mongod`',
     '.. |mongos| replace:: :binary:`~bin.mongos`',
     '.. |mongo| replace:: :binary:`~bin.mongo`',
-    '.. |multi-cluster| replace:: multi-cluster deployment',
-    '.. |multi-clusters| replace:: multi-cluster deployments',
+    '.. |multi-cluster| replace:: multi-Kubernestes-cluster deployment',
+    '.. |Multi-cluster| replace:: Multi-Kubernestes-cluster deployment',
+    '.. |multi-clusters| replace:: multi-Kubernetes-cluster deployments',
     '.. |oc| replace:: :xml:`<mono><link target="https://docs.openshift.com/container-platform/3.11/cli_reference/index.html">oc</link></mono>`',
     '.. |onprem| replace:: Ops Manager',
     '.. |onprem-link| replace:: :opsmgr:`Ops Manager </>`',

config/redirects

@@ -12,6 +12,9 @@ symlink: stable -> v1.16
 # Base URL
 raw: docs/kubernetes-operator/ -> ${base}/stable/
 
+# redirect for removal of multi-cluster quick start overview:
+[*-v1.12]: docs/kubernetes-operator/${version}/multi-cluster-quick-start-overview -> ${base}/stable/multi-cluster
+
 # Add redirects related to the addition of new topics for multi-cluster
 # beta security in the Operator v1.16.x, and single cluster LDAP:
 

source/multi-cluster-arch.txt

@@ -22,8 +22,9 @@ Features Not Available in the Beta Release
 ------------------------------------------
 
 .. important::
-   Use the beta release of the |multi-clusters| only in development
-   environments.
+
+   This feature is a beta release. Use |multi-cluster| 
+   deployments only in development environments.
 
 The following features of the |k8s-op-full| and the underlying |k8s|
 clusters are not available in the beta release of the |multi-clusters|:

source/multi-cluster-quick-start-overview.txt

@@ -16,6 +16,57 @@ Multi-Cluster Quick Start
    :depth: 2
    :class: singlecol
 
+.. _multi-cluster-services-tools-ref:
+
+Use the quick start to deploy a MongoDB replica set across three |k8s| 
+member clusters, using |gke| and |istio| service mesh.
+
+Services and Tools
+------------------
+
+The quick start relies on the following 
+services, tools, and their documentation:
+
+- |k8s| clusters. The quick start uses |gke| to provision multiple
+  |k8s| clusters. Each |k8s| member cluster hosts a MongoDB replica set
+  deployment and represents a data center that serves your application.
+
+- :github:`MongoDB Enterprise Kubernetes Operator repository
+  </mongodb/mongodb-enterprise-kubernetes>` with configuration
+  files that the |k8s-op-short| needs to deploy a |k8s| cluster.
+
+- :mdb-github:`MongoDB Helm Charts for Kubernetes </helm-charts>` with
+  charts for |multi-clusters|.
+
+- |istio| service mesh. 
+
+  - The quick start uses |istio| to facilitate
+    `DNS resolution
+    <https://istio.io/latest/docs/ops/configuration/traffic-management/dns-proxy/>`__
+    for MongoDB replica sets deployed in different |k8s| clusters. You
+    can use another service mesh solution as long as you ensure that
+    cross-cluster service FQDNs are resolvable.
+
+  - Documentation from |istio| to `Install Multicluster <https://istio.io/latest/docs/setup/install/multicluster/>`__.
+
+  - :github:`install_istio_separate_network script </mongodb/mongodb-enterprise-kubernetes/blob/master/tools/multicluster/install_istio_separate_network.sh>`
+    that is based on Istio documentation and provides an example
+    installation that uses the `multi-primary mode on different networks
+    <https://istio.io/latest/docs/setup/install/multicluster/multi-primary_multi-network/>`__.
+    If you use another service mesh solution, create your own script for
+    configuring separate networks to facilitate DNS resolution.
+
+- :github:`multi-cluster kubeconfig creator </mongodb/mongodb-enterprise-kubernetes/blob/master/tools/multicluster/main.go>`
+  tool that performs the following actions:
+
+  - Creates a single ``mongodb`` namespace in the central cluster and
+    each member cluster.
+  - Creates Service Accounts, Roles, and RoleBindings in the central
+    cluster and each member cluster.
+  - Puts Service Account token secrets from each member cluster into a
+    single ``kubeconfig`` file and saves the file in the central cluster.
+    This enables authorized access from the |k8s-op-short| installed in
+    the central cluster to the member clusters.
 
 :ref:`multi-cluster-quick-start-prereqs`
   Set up |gke| clusters, install tools, set the deployment's scope, and

source/multi-cluster-quick-start.txt

@@ -1,5 +1,6 @@
 :noprevnext:
 
+.. _multi-cluster-quick-start-overview:
 .. _multi-cluster:
 
 ===================================================================
@@ -15,40 +16,79 @@ Deploy MongoDB Resources across Multiple Kubernetes Clusters (Beta)
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
-:ref:`multi-cluster-quick-start-overview`
-  Learn about |multi-clusters|, terminology, and services and tools used
-  to deploy |multi-clusters| in this Quick Start.
+.. important::
 
-:ref:`multi-cluster-arch-ref`
-  Review the architecture diagram and limitations of the beta release.
+   This feature is a beta release. Use |multi-cluster| 
+   deployments only in development environments.
 
-:ref:`multi-cluster-quick-start-ref`
-  Deploy MongoDB replica sets on multiple |k8s| clusters that span
-  different regions and availability zones.
+Overview
+--------
 
+Using |multi-clusters|, you can deploy |k8s-op-full| to manage
+MongoDB deployments that span two or more |k8s| clusters. During the
+beta, the |k8s-op-short| supports deploying only replica sets across two or
+more |k8s| clusters. Deploying sharded clusters across two or
+more |k8s| clusters is not supported.
 
-:ref:`multi-cluster-secure-ref`
-  Secure database resources with |tls|, configure X.509 for client
-  authentication, and configure |tls| and X.509 for internal
-  communication in |multi-clusters|.
+The beta release of the |multi-clusters| enables different levels of resilience, depending on the needs of your enterprise application:
 
-:ref:`multi-cluster-connect-ref`
-  Access database resources in |multi-clusters| from inside or
-  outside |k8s|.
+- **Single Region, Multi AZ**. One or more |k8s| clusters where each
+  cluster has nodes deployed in different zones in the same region.
+  Such deployments protect MongoDB instances backing your enterprise
+  applications against zone and |k8s| cluster failures and offer increased
+  availability, disaster recovery, and data distribution within one
+  cloud region.
+
+- **Multi Region**. One or more |k8s| clusters where you deploy each
+  cluster in a different region, and within each region, deploy cluster
+  nodes in different availability zones. This gives your database
+  resilience against the loss of a |k8s| cluster, a zone, or an entire
+  cloud region.
+
+|Multi-cluster| deployments allow you to add MongoDB instances 
+in global clusters that span multiple geographic regions for increased
+availability and global distribution of data.
+
+A service mesh is required to enable inter-cluster communication between
+the replica set members deployed in different |k8s| clusters. MongoDB
+development has tested this feature using |istio|, but any service mesh 
+that provides FQDN resolution between Pods across clusters should work.
+
+.. _central-and-member-clusters:
+
+Central Cluster and Member Clusters
+-----------------------------------
+
+MongoDB recommends that you identify one cluster to act as 
+a **central cluster**. The central cluster hosts the |k8s-op-short| and 
+acts as the control plane for the multi-cluster deployment. This central
+cluster can also host replica set members. This documentation refers to
+other |k8s| clusters that host replica set members as **member clusters**.
+
+Communication between replica
+set members occurs over a service mesh, which means that your database 
+doesn't rely on the central cluster to function. Note that if the 
+central cluster fails, you can't use the |k8s-op-short| to change your
+deployment until access to this cluster is restored or until you
+redeploy the |k8s-op-short| to an available |k8s| cluster.
+
+You can host your application on any |k8s| cluster in the
+service mesh. Your application can be co-located on a
+member cluster with one of the replica set nodes that you deployed using
+the |k8s-op-short|, or you can host your application on a cluster that
+doesn't host replica set nodes or the |k8s-op-short|.
+
+To learn more, see the :ref:`multi-cluster-diagram`.
 
-:ref:`multi-cluster-troubleshooting`
-  Use the procedures in this section to troubleshoot your
-  |multi-clusters|.
 
 .. class:: hidden
 
    .. toctree::
       :titlesonly:
 
-      Overview </multi-cluster-quick-start-overview>
       Architecture and Limitations </multi-cluster-arch>
       Quick Start </multi-cluster-quick-start>
       Secure </multi-cluster-secure>

source/multi-cluster.txt

@@ -98,8 +98,9 @@ Added support for :ref:`LDAP client authentication
 <multi-cluster-secure-ldap-auth>` and for
 :ref:`managing database users with LDAP <multi-cluster-capabilities>`
 to |multi-clusters|.
-Use the beta release of the |multi-clusters| only in development
-environments.
+
+This feature is a beta release. Use |multi-cluster| 
+deployments only in development environments.
 
 .. _ent_op-1.16.1: