(DOCSP-32064) AppDB for multi-clusters, configuring and new spec params (#1427)

* (DOCSP-32064) AppDB for multi-clusters, configuring and new spec params
* Fixed syntax, added topology and clusterSpecList to OM resource spec
* Remove the minitoc per discussion with John W
* Added multi-cluster appdb config examples to steps
* Tech review. Made topology an optional param. Fixed the multi-cluster specific prereqs, to mention appdb deployment on all member clusters. Updated examples to remove members config when topology is set to multiCluster. Ready for a second review by Mircea.
* Moved topology to the list of optional params, per review
* Last comments from Lukasz and John W before this PR is ready for merging
* Undoing some changes as they must have been done on the other PR
* Included comments from Lukasz and Mircea
* Include comments from Raj
* Last comment from Lukasz
* Last copy revie from John W
* Final copy edits, ready for merge

Author: JuliaMongo

conf.py

@@ -218,6 +218,7 @@
     '.. |service-fullname| replace:: MongoDB Atlas',
     '.. |service-pricing| replace:: Atlas pricing page',
     '.. |service| replace:: Atlas',
+    '.. |mdb-support| replace:: `MongoDB Support <https://support.mongodb.com/welcome>`__',
     '.. |svc-api-key| replace:: Programmatic API Key',
     '.. |sms| replace:: :abbr:`SMS (short message service)`',
     '.. |sni| replace:: :abbr:`SNI (Server Name Indication)`',

snooty.toml

@@ -16,4 +16,4 @@ mdbtools-version = "100.1.0"
 mdbagent = "MongoDB Agent"
 appdb-agent-version = "10.2.15.5958-1_4.2.11-ent"
 mdb-ent-db = "MongoDB Enterprise Database"
-mdb-ent-db-version = "2.0.0"
+mdb-ent-db-version = "2.0.0"

source/faq.txt

@@ -72,4 +72,4 @@ Can I deploy MongoDB Server across multiple |k8s| clusters?
 -----------------------------------------------------------
 
 Yes. To learn more, see :ref:`Deploy MongoDB Resources on Multiple Kubernetes Clusters <multi-cluster>`.
-For help, `contact MongoDB Support <https://cloud.mongodb.com/links/support>`__.
+For help, contact `MongoDB Support <https://support.mongodb.com/welcome>`__

source/includes/admonitions/note-om-context-scope-multi-cluster.rst

@@ -1,4 +1,4 @@
-If you are deploying an |onprem| resource on a |multi-cluster|:
+If you are deploying an |onprem| resource in a |multi-cluster|:
 
 - Set the ``context`` to the name of the central cluster, such as:
   ``kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME"``.

source/includes/admonitions/note-om-external-connectivity-multi-cluster.rst

@@ -14,8 +14,8 @@ central cluster in a |multi-cluster|, use one of the following methods:
       --namespace "mongodb" \
        -f https://raw.githubusercontent.com/mongodb/mongodb-enterprise-kubernetes/master/samples/ops-manager/ops-manager-external.yaml
 
-- Add the central cluster and all member clusters to the service mesh.
-  The service mesh establishes communication from the central and all
+- Add the central cluster and all member clusters to the same service mesh.
+  The service mesh establishes communication from the the central and all
   member clusters to the |onprem| instance. To learn more, see the
   :ref:`Multi-Kubernetes-Cluster Quick Start <multi-cluster-quick-start-ref>`
   procedures and see the step that references the ``istio-injection=enabled``

source/includes/facts/fact-cannot-convert-om-crd-multi.rst

@@ -0,0 +1,5 @@
+You can't convert a single cluster |onprem| instance to a
+|multi-cluster| instance by modifying the
+:opsmgrkube:`topology <spec.applicationDatabase.topology>` and
+the :opsmgrkube:`clusterSpecList <spec.applicationDatabase.clusterSpecList>`
+settings in the CRD.

source/includes/facts/fact-om-in-multi-clusters-summary-of-diffs.rst

@@ -8,12 +8,42 @@ use the following procedures:
 These procedures are the same as the procedures for single clusters
 deployed with the |k8s-op-short| with the following exceptions:
 
-- Run the procedures to deploy |onprem| only on the central cluster of your |multi-cluster|.
-
-- Set the context and the |k8s-ns|.
+- **Set the context and the namespace.**
 
   .. include:: /includes/admonitions/note-om-context-scope-multi-cluster.rst
 
-- Configure external connectivity for |onprem|.
+- **Configure external connectivity for Ops Manager.**
 
   .. include:: /includes/admonitions/note-om-external-connectivity-multi-cluster.rst
+
+- **Deploy Ops Manager and the Application Database on the central cluster.**
+
+  You can choose to deploy |onprem| and the Application Database only on the central cluster,
+  using the same procedure as for single |k8s| clusters. To learn more,
+  see :ref:`Deploy an Ops Manager instance on the central cluster with TLS encryption <deploy-om-container>`.
+
+- **Deploy Ops Manager on the central cluster and the Application Database on selected member clusters.**
+
+  You can choose to deploy |onprem| on the central cluster and the Application
+  Database on a subset of selected member clusters, to increase the
+  Application Database's resilience and availability in |onprem|. Configure
+  the following settings in the |onprem| CRD:
+
+  - Use :opsmgrkube:`topology <spec.applicationDatabase.topology>` to specify the ``MultiCluster`` value.
+
+  - Specify the :opsmgrkube:`clusterSpecList <spec.applicationDatabase.clusterSpecList>` and
+    include in it the :opsmgrkube:`clusterName <spec.applicationDatabase.clusterSpecList.clusterName>`
+    of each selected |k8s| member cluster on which you want to deploy the Application Database, and the
+    number of :opsmgrkube:`members <spec.applicationDatabase.clusterSpecList.clusterName.members>`
+    (MongoDB nodes) in each |k8s| member cluster.
+
+  .. note::
+
+     If you deploy the Application Database on selected member clusters in
+     your |multi-cluster|, you must include the central cluster and
+     member clusters in the same service mesh configuration. This enables
+     bi-directional communication from |onprem| to the Application Database.
+
+  To learn more, see :ref:`Deploy Ops Manager <deploy-om-container>`,
+  review the |multi-cluster| example and specify ``MultiCluster`` for
+  :opsmgrkube:`topology <spec.applicationDatabase.topology>`.

source/includes/steps-deploy-k8s-opsmgr-http.yaml

@@ -5,26 +5,38 @@ inherit:
   file: steps-configure-kubectl-namespace.yaml
   ref: configure-kubectl-namespace
 ---
-title: "Copy the following example |onprem| |k8s| |k8s-obj|."
+title: "Copy one of the following |onprem| |k8s| |k8s-obj| examples."
 stepnum: 2
 level: 4
 ref: copy-k8s-example
 content: |
 
-   Change the highlighted settings to match your desired
-   |onprem| configuration.
+   Change the settings to match your |onprem| configuration.
 
-   .. literalinclude:: /reference/k8s/example-opsmgr-minimal.yaml
-      :language: yaml
-      :linenos:
+   .. tabs::
+
+     .. tab:: Single Kubernetes Cluster
+        :tabid: single-cluster-tls
+
+        .. literalinclude:: /reference/k8s/example-opsmgr-minimal.yaml
+           :language: yaml
+           :linenos:
+
+
+     .. tab:: Multi-Kubernetes Cluster
+        :tabid: multi-cluster-tls
+
+        .. literalinclude:: /reference/k8s/example-opsmgr-multi-cluster-http.yaml
+           :language: yaml
+           :linenos:  
 
 ---
 title: "Open your preferred text editor and paste the |k8s-obj| specification into a new text file."
 stepnum: 3
 level: 4
 ref: paste-k8s-example
 ---
-title: "Configure the settings included in the prior example."
+title: "Configure the settings included in the previous example."
 stepnum: 4
 level: 4
 ref: change-k8s-values
@@ -132,6 +144,33 @@ content: |
 
         - .. include:: /includes/facts/fact-which-appdb-version.rst
 
+      * - | ``spec``
+          | ``.applicationDatabase``
+          | ``.``:opsmgrkube:`~spec.applicationDatabase.topology`
+        - string
+        - *Optional*.
+
+          The type of the |k8s| deployment for the Application Database.
+          If omitted, the default is ``SingleCluster``.
+
+          If you specify ``MultiCluster``, the |k8s-op-short| ignores
+          values that you set for the
+          :setting:`spec.applicationDatabase.members <spec.members>`
+          field, if specified.
+
+          Instead, you must specify the :opsmgrkube:`clusterSpecList <spec.applicationDatabase.clusterSpecList>`
+          and include in it the :opsmgrkube:`clusterName <spec.applicationDatabase.clusterSpecList.clusterName>`
+          of each selected |k8s| member cluster on which you want to deploy the Application Database, and
+          the number of :opsmgrkube:`members <spec.applicationDatabase.clusterSpecList.clusterName.members>`
+          (MongoDB nodes) in each |k8s| cluster.
+
+          .. note::
+
+             .. include:: /includes/facts/fact-cannot-convert-om-crd-multi.rst
+
+          See also the :ref:`example of the resource specification <om_resource_spec_example_multi_cluster>`.
+
+        - ``MultiCluster``
 ---
 title: "Configure backup settings."
 stepnum: 5
@@ -175,7 +214,9 @@ content: |
         | ``.mongodbResourceRef``
         | ``.``:opsmgrkube:`~spec.backup.opLogStores.mongodbResourceRef.name`
       - string
-      - Name of the MongoDB database resource for the oplog store.
+      - Name of the |k8s-mdbrsc| or |mongodb-multi| for the oplog store.
+        The resource's ``metadata.name`` must match this name.
+        
       - ``my-oplog-db``
 
   You must also configure an :term:`S3 snapshot store <s3 snapshot store>` 
@@ -273,9 +314,9 @@ content: |
         | ``.mongodbResourceRef``
         | ``.``:opsmgrkube:`~spec.backup.blockStores.mongodbResourceRef.name`
       - string
-      - Name of the MongoDB database resource that you create for the 
-        blockstore. You must deploy this database resource in the same 
-        namespace as the |onprem| resource.
+      - Name of the |k8s-mdbrsc|  that you create for the blockstore.
+        You must deploy this database resource in the same namespace as
+        the |onprem| resource. The resource's ``metadata.name`` must match this name.
       - ``my-mongodb-blockstore``
 ---
 title: "Configure any additional settings for an |onprem| backup."
@@ -348,7 +389,7 @@ content: |
 
      status:
       applicationDatabase:
-       lastTransition: "2020-04-01T09:49:22Z"
+       lastTransition: "2022-04-01T09:49:22Z"
        message: AppDB Statefulset is not ready yet
        phase: Reconciling
        type: ""
@@ -376,22 +417,22 @@ content: |
 
       status:
         applicationDatabase:
-          lastTransition: "2020-04-01T09:50:20Z"
+          lastTransition: "2022-04-01T09:50:20Z"
           members: 3
           phase: Running
           type: ReplicaSet
-          version: "4.4.5-ubi8"
+          version: "6.0.5-ubi8"
        backup:
-        lastTransition: "2020-04-01T09:57:42Z"
+        lastTransition: "2022-04-01T09:57:42Z"
         message: The MongoDB object <namespace>/<oplogresourcename> 
           doesn't exist
         phase: Pending
         opsManager:
-          lastTransition: "2020-04-01T09:57:40Z"
+          lastTransition: "2022-04-01T09:57:40Z"
           phase: Running
           replicas: 1
           url: http://om-svc.cloudqa.svc.cluster.local:8080
-          version: "5.0.0"
+          version: "6.0.17"
 
   Backup remains in a ``Pending`` state until you configure the backup 
   databases.
@@ -459,7 +500,7 @@ content: |
   service, refer to the documentation for your solution.
 
 ---
-title: "Create credentials for the Kubernetes Operator."
+title: "Create credentials for the |k8s-op-short|."
 stepnum: 12
 level: 4
 optional: true
@@ -489,30 +530,30 @@ content: |
      kubectl get om -o yaml -w
 
   The command returns the URL of the |application| in the
-  ``status.opsManager.url`` field.
+  ``status.opsManager.url`` field, similar to the following example:
 
   .. code-block:: yaml
      :copyable: false
      :emphasize-lines: 17
 
       status:
         applicationDatabase:
-          lastTransition: "2020-04-01T10:00:32Z"
+          lastTransition: "2022-04-01T10:00:32Z"
           members: 3
           phase: Running
           type: ReplicaSet
-          version: "4.4.5-ubi8"
+          version: "6.0.5-ubi8"
        backup:
-        lastTransition: "2020-04-01T09:57:42Z"
+        lastTransition: "2022-04-01T09:57:42Z"
         message: The MongoDB object <namespace>/<oplogresourcename> 
           doesn't exist
         phase: Pending
         opsManager:
-          lastTransition: "2020-04-01T09:57:40Z"
+          lastTransition: "2022-04-01T09:57:40Z"
           phase: Running
           replicas: 1
           url: http://om-svc.cloudqa.svc.cluster.local:8080
-          version: "5.0.0"
+          version: "6.0.17"
 
   .. include:: /includes/admonitions/data-url-config-map-external-dbs.rst
 
@@ -579,21 +620,21 @@ content: |
 
      status:
        applicationDatabase:
-         lastTransition: "2020-04-01T10:00:32Z"
+         lastTransition: "2022-04-01T10:00:32Z"
          members: 3
          phase: Running
          type: ReplicaSet
-         version: "4.4.5-ubi8"
+         version: "6.0.5-ubi8"
        backup:
-         lastTransition: "2020-04-01T10:00:53Z"
+         lastTransition: "2022-04-01T10:00:53Z"
          phase: Running
-         version: "4.2.8"
+         version: "6.0.5-ubi8"
        opsManager:
-         lastTransition: "2020-04-01T10:00:34Z"
+         lastTransition: "2022-04-01T10:00:34Z"
          phase: Running
          replicas: 1
          url: http://om-svc.cloudqa.svc.cluster.local:8080
-         version: "5.0.0"
+         version: "6.0.17"
 
   See :doc:`/reference/troubleshooting` for information about the
   resource deployment statuses.