(DOCSP-18617) Watching multiple namespaces with the Operator (#751)

JuliaMongo · web-flow · commit 947158cf378e · 2021-10-01T14:58:21.000-04:00
* (DOCSP-18617) Operator can watch a list of namespaces * (DOCSP-18617) Operator can watch a list of namespaces * Edits * Address copy review and tech review. Add includes to reuse examples in two topics * Fixing the build warnings * Fixing the build --one file was accidentally moved, moving it back * Fixing the build --one file was accidentally moved, moving it back * Add a direct link to the Helm setting * Final polish, ready to merge
diff --git a/source/includes/admonitions/fact-create-service-account-namespaces.rst b/source/includes/admonitions/fact-create-service-account-namespaces.rst
@@ -1,7 +1,7 @@
 .. important::
 
-   To deploy |onprem| and |k8s-mdbrscs| in a |k8s-ns| other than the one
-   where you deploy the |k8s-op-short|, see :ref:`k8s-deployment-scopes`
-   for values you must use and additional steps you might have to
-   perform.
+   To deploy |onprem| and |k8s-mdbrscs| to one or more |k8s-nss| other
+   than the one where you deploy the |k8s-op-short|,
+   see :ref:`k8s-deployment-scopes` for values you must use and
+   additional steps you might have to perform.
    
diff --git a/source/includes/admonitions/fact-subset-of-namespaces.rst b/source/includes/admonitions/fact-subset-of-namespaces.rst
@@ -0,0 +1,3 @@
+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.
diff --git a/source/includes/code-examples/yaml-files/example-watch-namespaces-env-helm.yaml b/source/includes/code-examples/yaml-files/example-watch-namespaces-env-helm.yaml
@@ -0,0 +1,9 @@
+.. example::
+
+   .. code-block:: yaml
+      :emphasize-lines: 3
+
+      # Operator with name `mongodb-enterprise-operator-qa-envs` will
+      # watch ns-dev, ns-qa and ns-uat namespaces
+      helm install mongodb-operator helm_chart --set operator.watchNamespace="ns-dev\,ns-qa\,ns-uat" mongodb-enterprise-operator-qa-envs
+
diff --git a/source/includes/code-examples/yaml-files/example-watch-namespaces-staging-only-helm.yaml b/source/includes/code-examples/yaml-files/example-watch-namespaces-staging-only-helm.yaml
@@ -0,0 +1,9 @@
+.. example::
+
+   .. code-block:: yaml
+      :emphasize-lines: 3
+
+      # Operator with name `mongodb-enterprise-operator-staging` will
+      # watch ns-staging and ns-pre-prod
+      helm install mongodb-operator helm-chart --set operator.watchNamespace="ns-staging\,ns-pre-prod" mongodb-enterprise-operator-staging
+
diff --git a/source/includes/code-examples/yaml-files/example-watch-one-namespace-helm.yaml b/source/includes/code-examples/yaml-files/example-watch-one-namespace-helm.yaml
@@ -0,0 +1,8 @@
+.. example::
+
+   .. code-block:: yaml
+      :emphasize-lines: 2
+
+      # Watch one namespace
+      helm install mongodb-operator helm_chart --set operator.watchNamespace='namespace-to-watch' <...>
+
diff --git a/source/includes/code-examples/yaml-files/example-watch-two-namespaces-helm.yaml b/source/includes/code-examples/yaml-files/example-watch-two-namespaces-helm.yaml
@@ -0,0 +1,8 @@
+.. example::
+
+   .. code-block:: yaml
+      :emphasize-lines: 2
+
+      # Watch both namespace-a and namespace-b
+      helm install mongodb-operator helm_chart --set operator.watchNamespace="namespace-a\,namespace-b"
+
diff --git a/source/includes/op-setting-descs/watch-namespace.rst b/source/includes/op-setting-descs/watch-namespace.rst
@@ -1,13 +1,19 @@
-Namespace that the |k8s-op-short| watches for |k8s-mdbrsc|
+Namespaces that the |k8s-op-short| watches for |k8s-mdbrsc|
 changes. If this |k8s-ns| differs from the default, ensure that
-the Operator's ServiceAccount :k8sdocs:`can access
+the |k8s-op-short| ServiceAccount :k8sdocs:`can access
 </reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding>`
 this namespace.
 
-Use **\*** to specify *all namespaces*. To watch all namespaces, you
-must also assign the |k8s-cr| to the ``mongodb-enterprise-operator``
-ServiceAccount, which is the ServiceAccount used to run the
-|k8s-op-short|.
+- To watch *all namespaces*, specify **\*** and assign the |k8s-cr| to the
+  ``mongodb-enterprise-operator`` ServiceAccount that you use to run the
+  |k8s-op-short|.
+
+- To watch a *subset of all namespaces*, specify them in a
+  comma-separated list, escape each comma with a backslash,
+  and surround the list in quotes, such as
+  ``"operator.watchNamespace=ns1\,ns2"``.
+
+.. include:: /includes/admonitions/fact-subset-of-namespaces.rst
 
 .. include:: /includes/admonitions/fact-create-service-account-namespaces.rst
 
diff --git a/source/reference/helm-operator-settings.txt b/source/reference/helm-operator-settings.txt
@@ -341,18 +341,20 @@ The default value is **{+version+}**.
       operator:
         version: {+version+}
 
+.. _helm-watch-namespace:
+
 operator.watchNamespace
 -----------------------
 
 .. include:: /includes/op-setting-descs/watch-namespace.rst
 
-.. example::
+.. include:: /includes/code-examples/yaml-files/example-watch-one-namespace-helm.yaml
 
-   .. code-block:: yaml
-      :emphasize-lines: 2
+.. include:: /includes/code-examples/yaml-files/example-watch-two-namespaces-helm.yaml
 
-      operator:
-        watchNamespace: *
+.. include:: /includes/code-examples/yaml-files/example-watch-namespaces-env-helm.yaml
+
+.. include:: /includes/code-examples/yaml-files/example-watch-namespaces-staging-only-helm.yaml
 
 operator.watchedResources
 -------------------------
diff --git a/source/tutorial/set-scope-k8s-operator.txt b/source/tutorial/set-scope-k8s-operator.txt
@@ -31,8 +31,8 @@ You can set one of these scopes:
 
 .. _ns-scope-same-ns:
 
-Operator Uses Same Namespace as Resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Operator Uses the Same Single Namespace as Resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can set the scope for the |k8s-op-short| to use the same |k8s-ns| as
 resources. In this case, the |k8s-op-short| watches |onprem| and
@@ -43,32 +43,71 @@ uses the default namespace.
 
 .. _ns-scope-different-ns:
 
-Operator Uses Different Namespace than Resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Operator Uses a Subset of Namespaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can set the scope for the |k8s-op-short| to use a different |k8s-ns|
-than its resources. In this case, the |k8s-op-short| watches |onprem|
-and |k8s-mdbrscs| in a |k8s-ns| that you specify.
+You can set the scope for the |k8s-op-short| to use one or more |k8s-nss|
+that differ from the namespace used by the |k8s-op-short| resources.
+In this case, the |k8s-op-short| watches |onprem| and |k8s-mdbrscs|
+in a subset of |k8s-nss| that you specify.
+
+To install the |k8s-op-short| instances with this
+scope, use ``helm`` with the :ref:`helm-watch-namespace` parameter.
+
+.. include:: /includes/admonitions/fact-subset-of-namespaces.rst
 
-You can use ``helm`` to install the |k8s-op-short| with this scope.
 Follow the relevant :ref:`installation instructions
-<install-k8s-operator>` for ``helm``, but use the following command to
-set the namespace for the |k8s-op-short| to watch:
+<install-k8s-operator>` for ``helm``, but specify one or more namespaces
+in the :ref:`helm-watch-namespace` parameter for the |k8s-op-short| to
+watch:
+
+.. include:: /includes/code-examples/yaml-files/example-watch-one-namespace-helm.yaml
+
+.. include:: /includes/code-examples/yaml-files/example-watch-two-namespaces-helm.yaml
+
+.. include:: /includes/code-examples/yaml-files/example-watch-namespaces-env-helm.yaml
+
+.. include:: /includes/code-examples/yaml-files/example-watch-namespaces-staging-only-helm.yaml
+
+When installing the |k8s-op-short| to watch resources in one or more
+namespaces other than the namespace in which the |k8s-op-short| is
+deployed:
+
+1. Create the following resources:
+
+   - A |k8s-cr| with access to multiple resources. For the full resource
+     definition, see the
+     :github:`operator-roles.yaml </mongodb/mongodb-enterprise-kubernetes/blob/master/helm_chart/templates/operator-roles.yaml>`
+     example. This is a cluster-scoped resource.
+
+   - A |k8s-crb| on each namespace to watch. This ``clusterRoleBinding``
+     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``
+   in the default configuration files that you apply during the
+   installation.
+
+The following example illustrates how ``clusterRoles`` and
+``clusterRoleBindings`` work together in the cluster.
 
-.. code-block:: sh
+Suppose you create a ServiceAccount in the ``mongodb`` namespace, and
+then install the |k8s-op-short| in this namespace. The |k8s-op-short|
+uses this ServiceAccount.
 
-   helm install <chart-name> helm_chart \
-        --set operator.watchNamespace=<namespace> \
+To set the |k8s-op-short| scope to watch namespaces ``ns1`` and ``ns2``:
 
-Setting the namespace ensures that:
+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.
+   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``,
+   ``ns1`` and ``ns2``.
 
-- The namespace you want the |k8s-op-short| to watch has the correct
-  |k8s-cr| and |k8s-crb|. The ``clusterRole`` and ``clusterRoleBinding``
-  are included in the default configuration files that you apply during
-  the installation. To create the ``clusterRole`` and
-  ``clusterRoleBinding``, you must have
-  :k8sdocs:`cluster-admin privileges </reference/access-authn-authz/rbac/#user-facing-roles>`.
-- The |k8s-op-short| can watch and create resources in this namespace.
+See also :ref:`helm-watch-namespace`.
 
 .. _cluster-wide-scope:
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Watching a subset of namespaces is useful in deployments with`
	`2`	`+multiple \|k8s-op-short\| instances, where each \|k8s-op-short\| instance`
	`3`	`+watches a different subset of namespaces in your cluster.`