(DOCSP-23073) Multi-cluster namespace scope of many or all namespaces (#992)

* (DOCSP-23073) Multi-cluster namespace scope of many or all namespaces

* Fixing the build warnings

* Edits, may be ready for a review

* Fix build warning

* Edits

* Edits

* Edits

* Added copy review, ready for a review by Raj

* Apply suggestions from code review

Comments from Raj

Co-authored-by: Rajdeep Das <[email protected]>

* Cleanup

* Ready for a final tech review by Raj

* Introduced a typo now fixed

Co-authored-by: Rajdeep Das <[email protected]>

Author: JuliaMongo

source/includes/steps-multi-cluster-source.yaml

@@ -27,11 +27,10 @@ ref: run-multi-cluster-tool
 title: "Run the ``multi-cluster kubeconfig creator`` tool."
 content: |
 
-  By default, the |k8s-op-short| uses the ``mongodb`` namespace.
-  To simplify your installation, the tool creates one central cluster,
-  three member clusters, and a namespace labeled ``mongodb`` in each of
-  the clusters.
-  
+  By default, the |k8s-op-short| is scoped to the ``mongodb`` namespace.
+  The following command creates one central cluster, three member clusters,
+  and a |k8s-ns| labeled ``mongodb`` in each of the clusters.
+
   a. Change to the directory to which you cloned the |k8s-op-short|
      repository, and then to the directory that has the ``multi-cluster kubeconfig creator``
      tool.
@@ -110,9 +109,10 @@ level: 4
 title: "Install the |k8s-op-full| in the central cluster."
 ref: install-kubectl-mc
 content: |
-
-     Use the Helm charts for the |k8s-op-short| and multi-cluster deployments
-     to install |k8s-op-short| for managing your |multi-cluster|:
+     
+     Use the :mdb-github:`MongoDB Helm Charts for Kubernetes </helm-charts>`
+     for |multi-clusters| to install |k8s-op-short| for managing your
+     |multi-cluster|:
 
      .. code-block:: sh
 

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

@@ -78,6 +78,8 @@ deploy as part of this tutorial.
 
 To learn more, see the :ref:`multi-cluster-diagram`.
 
+.. _multi-cluster-services-tools-ref:
+
 Services and Tools
 ------------------
 

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

@@ -9,7 +9,7 @@ Multi-Cluster Prerequisites
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 2
+   :depth: 1
    :class: singlecol
 
 
@@ -88,6 +88,7 @@ Set up |gke| clusters:
         --num-nodes=5 \
         --machine-type "e2-standard-2"
 
+.. _multi-cluster-user-auth-clusters-ref:
 
 Obtain User Authentication Credentials for Central and Member clusters
 ----------------------------------------------------------------------
@@ -130,6 +131,153 @@ Install the following tools:
 
 3. `Install Helm <https://helm.sh/docs/intro/install/>`__.
 
+
+.. _mc-namespace-scope-ref:
+
+Set the Deployment's Scope
+--------------------------
+
+By default, the multi-cluster |k8s-op-short| is scoped to the |k8s-ns|
+in which it is installed. The |k8s-op-short| reconciles the
+``MongoDBMulti`` custom resource deployed in the same namespace as the
+|k8s-op-short|.
+
+When you run the :github:`multi-cluster kubeconfig creator
+</mongodb/mongodb-enterprise-kubernetes/blob/master/tools/multicluster/main.go>`
+tool as part of the :ref:`multi-cluster Quick Start procedure
+<multi-cluster-quick-start-procedure>`, and don't modify the tool's
+settings, the tool:
+
+- 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.
+- Applies the correct permissions for service accounts.
+- Uses these settings to create your |multi-cluster|.
+
+Once the multi-cluster is deployed, the |k8s-op-short| starts watching
+|k8s-mdbrscs| in the ``mongodb`` |k8s-ns|.
+
+To configure the |k8s-op-short| with the correct permissions to deploy
+in multiple or all namespaces, run the following command and specify the
+namespaces that you would like the |k8s-op-short| to watch.
+
+.. code-block:: sh
+
+   cd tools/multicluster
+   go run main.go \
+    -central-cluster="e2e.operator.mongokubernetes.com" \
+    -member-clusters="e2e.cluster1.mongokubernetes.com,e2e.cluster2.mongokubernetes.com,e2e.cluster3.mongokubernetes.com" \
+    -member-cluster-namespace="mongodb2" \
+    -central-cluster-namespace="mongodb2" \
+    -cluster-scoped="true"
+
+When you install the |multi-cluster| to multiple or all |k8s-nss|, you
+can configure the |k8s-op-short| to:
+
+- :ref:`Watch Resources in Multiple Namespaces <mc-cluster-many-namespaces-ref>`
+- :ref:`Watch Resources in All Namespaces <mc-cluster-all-namespaces-ref>`
+
+.. _mc-cluster-many-namespaces-ref:
+
+Watch Resources in Multiple Namespaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you set the scope for the |multi-cluster| to many |k8s-nss|, you can
+configure the |k8s-op-short| to watch |k8s-mdbrscs| in these namespaces
+in the |multi-cluster|.
+
+.. tabs::
+
+   .. tab:: Using kubectl
+      :tabid: mc-kubectl
+
+
+      1. Use the :github:`mongodb-enterprise.yaml
+         </mongodb/mongodb-enterprise-kubernetes/blob/master/mongodb-enterprise.yaml>`
+         sample |yaml| file from the MongoDB Enterprise Kubernetes Operator GitHub
+         repository.
+      #. Set the ``spec.template.spec.containers.name.env.name:WATCH_NAMESPACE`` in
+         :github:`mongodb-enterprise.yaml
+         </mongodb/mongodb-enterprise-kubernetes/blob/master/mongodb-enterprise.yaml>`
+         to the comma-separated list of namespaces that you would like
+         the |k8s-op-short| to watch:
+
+         .. code-block:: sh
+
+            WATCH_NAMESPACE: "$namespace1,$namespace2,$namespace3"
+
+
+   .. tab:: Using Helm
+      :tabid: mc-with-helm
+
+      Run the following command and replace the values in the last line
+      with the namespaces that you would like the |k8s-op-short| to
+      watch.
+
+      .. code-block:: sh
+
+         helm upgrade \
+           --install \
+           mongodb-enterprise-operator-multi-cluster \
+           mongodb/enterprise-operator \
+           --namespace mongodb \
+           --set namespace=mongodb \
+           --version <mongodb-kubernetes-operator-version>\
+           --set operator.name=mongodb-enterprise-operator-multi-cluster \
+           --set operator.createOperatorServiceAccount=false \
+           --set "multiCluster.clusters=$MDB_CLUSTER_1_FULL_NAME,$MDB_CLUSTER_2_FULL_NAME,$MDB_CLUSTER_3_FULL_NAME"
+           --set operator.watchNamespace="$namespace1,$namespace2,$namespace3"
+
+.. _mc-cluster-all-namespaces-ref:
+
+Watch Resources in All Namespaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you set the scope for the |multi-cluster| to all |k8s-nss| instead 
+of the default ``mongodb`` namespace, you can configure the |k8s-op-short|
+to watch |k8s-mdbrscs| in all namespaces in the |multi-cluster|.
+
+.. tabs::
+
+   .. tab:: Using kubectl
+      :tabid: mc-kubectl
+
+
+      1. Use the :github:`mongodb-enterprise.yaml
+         </mongodb/mongodb-enterprise-kubernetes/blob/master/mongodb-enterprise.yaml>`
+         sample |yaml| file from the MongoDB Enterprise Kubernetes
+         Operator GitHub repository.
+      #. Set the ``spec.template.spec.containers.name.env.name:WATCH_NAMESPACE``
+         in :github:`mongodb-enterprise.yaml
+         </mongodb/mongodb-enterprise-kubernetes/blob/master/mongodb-enterprise.yaml>`
+         to ``*``:
+
+         .. code-block:: sh
+
+            WATCH_NAMESPACE: "*"
+
+   .. tab:: Using Helm
+      :tabid: mc-with-helm
+
+      Run the following command:
+
+      .. code-block:: sh
+
+         helm upgrade \
+           --install \
+           mongodb-enterprise-operator-multi-cluster \
+           mongodb/enterprise-operator \
+           --namespace mongodb \
+           --set namespace=mongodb \
+           --version <mongodb-kubernetes-operator-version>\
+           --set operator.name=mongodb-enterprise-operator-multi-cluster \
+           --set operator.createOperatorServiceAccount=false \
+           --set "multiCluster.clusters=$MDB_CLUSTER_1_FULL_NAME,$MDB_CLUSTER_2_FULL_NAME,$MDB_CLUSTER_3_FULL_NAME"
+           --set ​​operator.watchNamespace="*"
+
+.. _mc-cluster-check-connectivity-ref:
+
 Check Connectivity Across Clusters
 ----------------------------------
 

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

@@ -12,11 +12,19 @@ Quick Start Procedure
    :depth: 2
    :class: singlecol
 
-Before you begin, learn about |multi-clusters| implementation and complete
-the prerequisite steps:
+Before you begin, learn about |multi-clusters| implementation,
+`multi-cluster services and tools <multi-cluster-services-tools-ref>`,
+and complete the prerequisite steps:
 
 - :ref:`Overview <multi-cluster-quick-start-overview>`
 - :ref:`Prerequisites <multi-cluster-quick-start-prereqs>`
 
+.. note::
+
+   The following procedure scopes your |multi-cluster| to a single
+   |k8s-ns| named ``mongodb``. You can :ref:`set scope for your
+   deployment <mc-namespace-scope-ref>` and use another |k8s-ns|,
+   multiple, or all namespaces.
+
 .. include:: /includes/steps/multi-cluster-beta-quick-start.rst
 

source/multi-cluster-quick-start.txt

@@ -14,15 +14,11 @@ Multi-Cluster Quick Start
 
 
 :ref:`multi-cluster-quick-start-prereqs`
-  Set the environment variables and the
-  `available GKE zones <https://cloud.google.com/compute/docs/regions-zones#available>`__
-  where you deploy the clusters, set up |gke| clusters, save user
-  authentication credentials for the central and member clusters,
-  install tools, including a service mesh, Helm, and Go, and establish
-  cluster connectivity.
+  Set up |gke| clusters, install tools, set the deployment's scope, and
+  check connectivity across member clusters.
 
 :ref:`multi-cluster-quick-start-procedure`
-  Follow the steps in this section to deploy |multi-clusters|.
+  Deploy |multi-clusters|.
 
 
 .. class:: hidden

source/multi-cluster.txt

@@ -15,12 +15,12 @@ Deploy Multiple Clusters (Beta)
    :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.
+  Learn about |multi-clusters|, terminology, and services and tools used
+  to deploy |multi-clusters| in this Quick Start.
 
 :ref:`multi-cluster-arch-ref`
   Review the architecture diagram and limitations of the beta release.
 
-
 :ref:`multi-cluster-quick-start-ref`
   Deploy MongoDB replica sets on multiple |k8s| clusters that span
   different regions and availability zones.
@@ -44,10 +44,10 @@ Deploy Multiple Clusters (Beta)
    .. toctree::
       :titlesonly:
 
-      /multi-cluster-quick-start-overview
-      /multi-cluster-arch
-      /multi-cluster-quick-start
-      /multi-cluster-secure
-      /multi-cluster-connect
-      /multi-cluster-troubleshooting
+      Overview </multi-cluster-quick-start-overview>
+      Architecture and Limitations </multi-cluster-arch>
+      Quick Start </multi-cluster-quick-start>
+      Secure </multi-cluster-secure>
+      Access Resources </multi-cluster-connect>
+      Troubleshoot </multi-cluster-troubleshooting>
 

source/tutorial/set-scope-k8s-operator.txt

@@ -84,12 +84,12 @@ deployed:
      will bind the ``clusterRole`` you created with the ServiceAccount
      the |k8s-op-short| is using on the namespace where you install it.
 
-2. Include the ``clusterRole`` and ``clusterRoleBinding``
+2. Include the |k8s-cr| and |k8s-crb|
    in the default configuration files that you apply during the
    installation.
 
-The following example illustrates how ``clusterRoles`` and
-``clusterRoleBindings`` work together in the cluster.
+The following example illustrates how the |k8s-cr| and |k8s-crb| work
+together in the cluster.
 
 Suppose you create a ServiceAccount in the ``mongodb`` namespace, and
 then install the |k8s-op-short| in this namespace. The |k8s-op-short|
@@ -100,8 +100,8 @@ To set the |k8s-op-short| scope to watch namespaces ``ns1`` and ``ns2``:
 1. Obtain :k8sdocs:`cluster-admin privileges </reference/access-authn-authz/rbac/#user-facing-roles>`.
 2. Using these privileges, create a cluster-wide, non-namespaced |k8s-cr|.
 3. Create a |k8s-crb| in three namespaces: ``mongodb``, ``ns1``
-   and ``ns2``. This ``clusterRoleBinding`` will bind the
-   ``clusterRole`` to the ServiceAccount in the ``mongodb`` namespace.
+   and ``ns2``. This |k8s-crb| will bind the
+   |k8s-cr| to the ServiceAccount in the ``mongodb`` namespace.
    The ``clusterRoleBinding`` will allow the |k8s-op-short| deployed in
    the ``mongodb`` namespace to access the resources described in the
    ``clusterRole`` of the target namespace, that is, in ``mongodb``,