(DOCSP-32707) Decide which Operators, for Single or Multi k8s Clusters (#1467)

JuliaMongo · jwilliams-mongo · commit d409dd166758 · 2025-04-14T17:11:22.000-05:00
* (DOCSP-32707) Decide which Operators, for Single or Multi k8s Clusters * (DOCSP-32707) Tech review and change of direction * Fix build warnings for the new conf.py substitution * Second round of reviews from Dan M, close to done I hope * Renamed one file, continued to turn the initial recommendation into a different recommendation in line with product direction * Edits * Edits * Edits * Edits * Added to multi-cluster namespace prereqs * Fix the build * build * Edits * a few more edits, to shorten and clarify * a few more edits, to shorten and clarify * edits again * Tech review * A few more review comments * Fix the build warning * Include copy review comments from Will * Include copy review comments from Will * Last copy review comments
diff --git a/conf.py b/conf.py
@@ -153,6 +153,9 @@
     '.. |k8s-mdbrsc| replace:: ``MongoDB`` resource',
     '.. |mongodb-multi| replace:: ``MongoDBMultiCluster`` resource',
     '.. |mongodb-multis| replace:: ``MongoDBMultiCluster`` resources',
+    '.. |mongodbusers| replace:: ``MongoDBUsers`` resources',
+    '.. |opsmanager-resource| replace:: ``Ops Manager`` resource',
+    '.. |opsmanager-resources| replace:: ``Ops Manager`` resources',
     '.. |k8s-nodes| replace:: `nodes <https://kubernetes.io/docs/concepts/architecture/nodes/>`__',
     '.. |k8s-node| replace:: `node <https://kubernetes.io/docs/concepts/architecture/nodes/>`__',
     '.. |k8s-nss| replace:: `namespaces <https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/>`__',
diff --git a/source/faq.txt b/source/faq.txt
@@ -35,7 +35,7 @@ configuration of MongoDB Server features, such as database backups,
 through interaction with |cloud| or |onprem|.
 
 Why should I run MongoDB Server and MongoDB Enterprise Advanced in |k8s|?
---------------------------------------------------------------------------
+------------------------------------------------------------------------------------
 
 When you deploy MongoDB Server or MongoDB Enterprise Advanced in |k8s| 
 through the |k8s-op-full|, your deployments can benefit from the 
@@ -46,7 +46,7 @@ through the |k8s-op-full|. The |k8s-op-full| simplifies your daily workflows
 and makes it easier for MongoDB technical support staff to assist you when needed.
 
 Which |k8s| platforms are supported for MongoDB Server deployments?
--------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 MongoDB Server supports any platform that builds upon native |k8s| without
 changing the default logic or behavior. In practice, this means that
@@ -55,21 +55,63 @@ MongoDB Server supports any |k8s| platform
 To learn more, see :ref:`MongoDB Kubernetes Operator Compatibility <k8s-compatibility>`.
 
 How many deployments can |k8s-op-full| support?
------------------------------------------------
+--------------------------------------------------------------
 
 |k8s-op-short| can support up to 50 deployments. However, changes made to
 large numbers of deployments at the same time result in long reconciliation times.
 To avoid prolonged reconciliation times, limit a given |k8s-op-short| instance
-to 20 deployments. To learn more, see the :ref:`production notes <deploy_recommended-number-sets>`.
+to 20 deployments. To learn more, see the :ref:`Deploy the Recommended Number of MongoDB Replica Sets <deploy_recommended-number-sets>`.
 
 Should I run MongoDB Server in |k8s| in the same cluster as the application using it?
---------------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------
 
 To help minimize latency, consider colocating your database and applications on
 the same |k8s| cluster if your deployment architecture allows this.
 
 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 |mdb-support|.
+
+What is the difference between using the |k8s-op-short| for managing |multi-clusters| and  managing a single |k8s| cluster?
+-----------------------------------------------------------------------------------------------------------------------------------
+
+To use the |k8s-op-short| for managing a |multi-cluster|, you must set up a specific set of 
+|k8s| :k8sdocs:`Roles, ClusterRoles </reference/access-authn-authz/rbac/#role-and-clusterrole>`, 
+:k8sdocs:`RoleBindings, ClusterRoleBindings </reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding>`,
+and :k8sdocs:`ServiceAccounts </tasks/configure-pod-container/configure-service-account/>`.
+
+The |k8s-op-short| used for a |multi-cluster| can also reconcile a single |k8s| cluster resource.
+To learn more, see :ref:`faq-many-operators`.
+
+.. _faq-many-operators:
+
+Does MongoDB support running more than one |k8s-op-short| instance?
+--------------------------------------------------------------------------------
+
+If possible, we recommend that you set up a single |k8s-op-short| instance to
+watch one, many, or all namespaces within your |k8s| cluster. By default,
+the |k8s-op-short| watches all |k8s-custom-resource| types that you choose
+to deploy, and you don't need to configure it to watch specific resource types.
+
+However, once you reach a :ref:`performance limit <deploy_recommended-number-sets>`
+for the number of deployments a single |k8s-op-short| instance can support,
+you can set up an additional |k8s-op-short| instance. At this point,
+consider how you want to divide up management of resources in the |k8s| cluster.
+Use the following recommendations listed in the order of priority:
+
+- Ensure that each |k8s-op-short| instance is watching different and non-overlapping
+  namespaces within the |k8s| cluster.
+- Alternatively, configure different instances of the |k8s-op-short| to watch
+  different resource types, either in different namespaces or overlapping namespaces.
+  
+  If you choose to use overlapping namespaces, ensure that each |k8s-op-short|
+  instance watches different types of resources to avoid conflict that would
+  result in two instances of the |k8s-op-short| attempting to manage
+  the same resources.
+
+.. note::
+
+   Before you configure another |k8s-op-short| instance, verify that none of its
+   namespaces are included in the subset of namespaces for the existing |k8s-op-short| instance.
diff --git a/source/includes/admonitions/fact-subset-of-namespaces.rst b/source/includes/admonitions/fact-subset-of-namespaces.rst
@@ -1,3 +1,7 @@
-Watching a subset of namespaces is useful in deployments with
-multiple |k8s-op-short| instances, where each |k8s-op-short| instance
-watches a different subset of namespaces in your cluster.
+Watching a subset of namespaces is useful in deployments where a single
+|k8s-op-short| instance watches a different cluster resource type.
+For example, you can configure the |k8s-op-short| to watch |k8s-mdbrscs|
+in one subset of namespaces, and to watch |mongodb-multis| in another
+subset of namespaces. To avoid race conditions during resource reconciliation,
+for each custom resource type that you want the |k8s-op-short| to watch,
+ensure that you set scope to a distinct subset of namespaces.
diff --git a/source/includes/admonitions/note-k8s-non-overlapping-namespaces-for-diff-rsrc-types.rst b/source/includes/admonitions/note-k8s-non-overlapping-namespaces-for-diff-rsrc-types.rst
@@ -0,0 +1,5 @@
+.. note::
+
+   Install and set up a single |k8s-op-short| instance and configure it
+   to watch one, many, or all custom resources in different, non-overlapping
+   subsets of namespaces. See also :ref:`faq-many-operators`
diff --git a/source/includes/facts/fact-multi-cluster-plugin-actions-setup.rst b/source/includes/facts/fact-multi-cluster-plugin-actions-setup.rst
@@ -1,7 +1,9 @@
 - Creates a default ConfigMap named ``mongodb-enterprise-operator-member-list``
   that contains all the member clusters of the |multi-cluster|. This name is
   hard-coded and you can't change it. See :ref:`Known Issues <hardcoded_configmap_multi-clusters>`.
-- Creates |k8s-service-accounts|, Roles, and RoleBindings in the central
-  cluster and each member cluster.
+- Creates :k8sdocs:`ServiceAccounts </tasks/configure-pod-container/configure-service-account/>`,
+  :k8sdocs:`Roles, ClusterRoles </reference/access-authn-authz/rbac/#role-and-clusterrole>`,
+  :k8sdocs:`RoleBindings and ClusterRoleBindings </reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding>`
+  in the central cluster and each member cluster.
 - Applies the correct permissions for service accounts.
 - Uses the preceding settings to create your |multi-cluster|.
diff --git a/source/multi-cluster-prerequisites.txt b/source/multi-cluster-prerequisites.txt
@@ -158,13 +158,13 @@ and :k8sdocs:`ServiceAccounts </tasks/configure-pod-container/configure-service-
   service accounts to your |multi-cluster| with the ``kubectl apply`` command. This may be
   necessary for certain highly automated workflows. MongoDB provides sample configuration files.
 
-  For namespace-scoped resources:  
+  For custom resources scoped to a subset of namespaces:
 
   - :github-raw:`Roles, Role Bindings, and Service Accounts for your Central Cluster </mongodb/mongodb-enterprise-kubernetes/master/samples/multi-cluster-cli-gitops/resources/rbac/namespace_scoped_central_cluster.yaml>`
 
   - :github-raw:`Roles, Role Bindings, and Service Accounts for your Member Clusters </mongodb/mongodb-enterprise-kubernetes/master/samples/multi-cluster-cli-gitops/resources/rbac/namespace_scoped_member_cluster.yaml>`
 
-  For cluster-scoped resources:
+  For custom resources scoped to a cluster-wide namespace:
 
   - :github-raw:`ClusterRoles, ClusterRoleBindings, and ServiceAccounts for your Central Cluster </mongodb/mongodb-enterprise-kubernetes/master/samples/multi-cluster-cli-gitops/resources/rbac/cluster_scoped_central_cluster.yaml>`
 
@@ -204,7 +204,7 @@ Once the |k8s-op-short| creates the |multi-cluster|, 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
+in a subset or all namespaces, run the following command and specify the
 namespaces that you would like the |k8s-op-short| to watch.
 
 .. code-block:: sh
@@ -222,6 +222,8 @@ 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>`
 
+.. include:: /includes/admonitions/note-k8s-non-overlapping-namespaces-for-diff-rsrc-types.rst
+
 .. _mc-cluster-many-namespaces-ref:
 
 Watch Resources in Multiple Namespaces
diff --git a/source/tutorial/plan-k8s-install-single-or-multi-clusters.txt b/source/tutorial/plan-k8s-install-single-or-multi-clusters.txt
@@ -0,0 +1,80 @@
+:noprevnext:
+
+.. _k8s-which-to-install:
+
+==========================================================================================
+Choose |k8s-op-short| Installation Mode: Single- or Multi-|k8s| Clusters
+==========================================================================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+The |k8s-op-short| can manage custom resources for single- and multi-|k8s|
+clusters. Before you install the |k8s-op-short|, decide which type of
+|k8s| cluster deployment you want to support, single- or multi-|k8s| cluster.
+
+.. _one-operator-for-single-k8s-cluster:
+
+|k8s-op-short| Watches Single-|k8s| Cluster Resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can configure the |k8s-op-short| to watch |opsmanager-resources| and |k8s-mdbrscs|
+for a replica set or a sharded cluster in a single |k8s| cluster.
+For steps, see :ref:`Install the Operator <install-k8s-operator>`.
+
+.. _one-operator-for-multi-k8s-clusters:
+
+|k8s-op-short| Watches Multi-|k8s| Cluster Resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can configure the |k8s-op-short| to watch |opsmanager-resources|, |k8s-mdbrscs|,
+and |mongodb-multis| for a replica set in a multi-|k8s| cluster. For steps,
+see :ref:`Multi-Kubernetes-Cluster Quick Start <multi-cluster-quick-start-ref>`.
+
+.. _one-operator-for-single-and-multi-k8s-clusters:
+
+|k8s-op-short| Watches Resources in a Single- and Multi-|k8s| Cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can configure the |k8s-op-short| to watch the following types of |k8s-crds|:
+
+- |k8s-mdbrscs|
+- |opsmanager-resources|
+- |mongodbusers|
+- |mongodb-multis|
+
+Depending on the watched resources, the |k8s-op-short| reconciles resources
+based on the given |k8s-crd|.
+
+To support custom resources deployed in single- and multi-|k8s| clusters,
+set up one instance of the |k8s-op-short| that will watch for and reconcile
+custom resources for a single |k8s| cluster and a |multi-cluster|.
+Use different non-overlapping subsets of namespaces for each type of resource.
+
+Set ``.Values.operator.watchedResources`` as follows:
+
+.. code-block:: yaml
+
+   -watch-resource=MongoDB \
+   -watch-resource=OpsMnagers \
+   -watch-resource=MongoDBusers \
+   -watch-resource=MongoDBMultiCluster
+
+.. include:: /includes/admonitions/note-k8s-non-overlapping-namespaces-for-diff-rsrc-types.rst
+
+Next Steps
+----------
+
+After deciding how you want to install the |k8s-op-short|, you can:
+
+- Set the :ref:`scope of your deployments <k8s-deployment-scopes>` for
+  single |k8s| clusters, or :ref:`set the multi-Kubernetes cluster deployment's scope <mc-namespace-scope-ref>`.
+- Install single-|k8s| cluster. For single-|k8s| clusters, review the
+  :ref:`considerations <k8s-considerations>`, complete the :ref:`prerequisites <k8s-prerequisites>`
+  and :ref:`install the Kubernetes Operator <install-k8s-operator>`.
+- Install the |k8s-op-short| in a |multi-cluster|. See the :ref:`Multi-Kubernetes-Cluster Quick Start <multi-cluster-quick-start-ref>`.
diff --git a/source/tutorial/plan-k8s-operator-install.txt b/source/tutorial/plan-k8s-operator-install.txt
@@ -38,6 +38,10 @@ resources.
 :ref:`Container Images <k8s-container-images>`
   Review container image details.
 
+:ref:`Single- or Multi-Kubernetes Clusters <k8s-which-to-install>`
+  Decide whether to set up single or multiple |k8s| clusters for your custom
+  MongoDB resources.
+
 :ref:`Set Deployment Scope <k8s-deployment-scopes>`
   Set the scope for the |k8s-op-short| deployment by configuring which
   type of namespace the |k8s-op-short| should use.
@@ -57,6 +61,7 @@ resources.
       Architecture </tutorial/plan-k8s-op-architecture>
       Compatibility </tutorial/plan-k8s-op-compatibility>
       Container Images </tutorial/plan-k8s-op-container-images>
+      Single- or Multi-Kubernetes Clusters </tutorial/plan-k8s-install-single-or-multi-clusters>
       Set Deployment Scope </tutorial/set-scope-k8s-operator>
       /tutorial/plan-k8s-op-considerations
       /tutorial/plan-k8s-op-prerequisites
