(DOCSP-18122) ImagePullSecret is synchronized across all watched namespaces (#730)

* (DOCSP-18122) imagePullSecret is syncrhonized to all watched  namespaces

* Fixing the build warnings

* Edits, and fixing build warnings due to bad links

* Fixing rst

* Edits

* Include first batch of comments from copy review. To be continued

* Finished adding copy review

* Fixing the build

* Fixing the build 2

* One edit, and fixing a warning in the build. Ready for a second copy review

* Second round of copy review by John W

* fixing the build

* Fixing the link, minor edits. Ready for the next round of reviews

* edits

* Addressed the last copy review comment. Ready for a tech review

Author: JuliaMongo

conf.py

@@ -166,6 +166,7 @@
     '.. |k8s-secrets| replace:: `secrets <https://kubernetes.io/docs/concepts/configuration/secret/>`__',
     '.. |k8s-secret| replace:: `secret <https://kubernetes.io/docs/concepts/configuration/secret/>`__',
     '.. |k8s-service| replace:: `service <https://kubernetes.io/docs/concepts/services-networking/service/>`__',
+    '.. |k8s-service-accounts| replace:: `service accounts <https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/>`__',
     '.. |k8s-service-type| replace:: `ServiceType <https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types>`__',
     '.. |k8s-statefulsets| replace:: `StatefulSets <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`__',
     '.. |k8s-statefulset| replace:: `StatefulSet <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`__',

source/includes/admonitions/fact-use-metadata-name.rst

@@ -3,5 +3,12 @@ images from the repository.
 
 .. important::
 
-   OpenShift requires this setting. Define it in this file or
-   pass it when you install the |k8s-op-short| using Helm.
+   OpenShift requires this setting. Define it in the
+   ``imagePullSecrets`` setting in this file or pass it when you install
+   the |k8s-op-short| using Helm.
+   If you use the |k8s-op-short| to deploy MongoDB resources to
+   :ref:`multiple namespaces <ns-scope-different-ns>` or with a
+   :ref:`cluster-wide scope <cluster-wide-scope>`, create the secret
+   only in the namespace where you installed the |k8s-op-short|.
+   The |k8s-op-short| synchronizes the secret across all watched
+   namespaces.

source/includes/op-setting-descs/registry-imagepullsecrets.rst

@@ -173,7 +173,9 @@ content: |
 
   Add the name of your ``<openshift-pull-secret>`` to the
   ``registry.imagePullSecrets`` setting in the
-  ``helm_chart/values-openshift.yaml`` file:
+  ``helm_chart/values-openshift.yaml`` file.
+  To learn more, see the ``registry.imagePullSecrets`` setting in the
+  :doc:`Helm installation settings </reference/helm-operator-settings>`.
 
   .. code-block:: sh
      :emphasize-lines: 3

source/includes/steps-helm-master.yaml

@@ -44,12 +44,22 @@ level: 4
 ref: install-master-edit-yaml
 content: |
 
-   {{pullsecret}}
+  To learn about optional |k8s-op-short| installation settings,
+  see :ref:`Operator kubectl and oc Installation Settings
+  <meko-op-install-settings-kubectl-oc>`.
+---
+title: "Add your ``<openshift-pull-secret>`` to the ``ServiceAccount``
+definitions in the |k8s-op-short| |yaml| before {{method}} it."
+level: 4
+ref: add-pullsecret-yaml
+content: |
 
-   #. You might need to add one or more optional settings.
+   .. literalinclude:: /includes/openshift-service-accounts.yaml
+      :language: yaml
+      :emphasize-lines: 11-12, 22-23, 33-34
 
-      To learn about optional |k8s-op-short| installation settings,
-      see :ref:`Operator kubectl and oc Installation Settings <meko-op-install-settings-kubectl-oc>`.
+   To learn more, see the ``registry.imagePullSecrets`` setting in the
+   :doc:`Helm installation settings </reference/helm-operator-settings>`.
 ---
 title: "{{method}}"
 level: 4

source/includes/steps-install-master.yaml

@@ -24,20 +24,23 @@ inherit:
 stepnum: 3
 replacement:
   method: installing
-  pullsecret: |
 
-    #. You must add your ``<openshift-pull-secret>`` to the 
-       ``ServiceAccount`` definitions:
 
-       .. literalinclude:: /includes/openshift-service-accounts.yaml
-          :language: yaml
-          :emphasize-lines: 11-12, 22-23, 33-34
+---
+ref: add-oc-pullsecret-yaml
+inherit:
+  file: steps-install-master.yaml
+  ref: add-pullsecret-yaml
+stepnum: 4
+replacement:
+  method: installing
+
 ---
 ref: install-oc-install
 inherit:
   file: steps-install-master.yaml
   ref: install-master-install
-stepnum: 4
+stepnum: 5
 replacement:
   method: "Install the |k8s-op-short| using the following
    |oc| command:"

source/includes/steps-install-oc.yaml

@@ -68,7 +68,7 @@ content: |
      the |onprem| host's clock falls out of sync, that host can't
      communicate with the |k8s-op-short|. 
 
-     To learn how to check your |ntp| service for your Ops Manager
+     To learn how to check your |ntp| service for your |onprem|
      host, see the documentation for
      `Ubuntu <https://help.ubuntu.com/lts/serverguide/NTP.html>`__ or
      `RHEL
@@ -78,9 +78,17 @@ content: |
 stepnum: 5
 level: 4
 ref: create-k8s-secret
-title: "**Required for OpenShift Installs:** Create a |k8s-secret| that contains credentials authorized to pull images from the ``registry.connect.redhat.com`` repository."
+title: "**Required for OpenShift Installs:** Create a |k8s-secret| that
+contains credentials authorized to pull images from the
+``registry.connect.redhat.com`` repository."
 content: |
 
+  If you use the |k8s-op-short| to deploy MongoDB
+  resources to :ref:`multiple namespaces <ns-scope-different-ns>` or with
+  a :ref:`cluster-wide scope <cluster-wide-scope>`, create the secret
+  only in the namespace where you intend to deploy the |k8s-op-short|. The
+  |k8s-op-short| synchronizes the secret across all watched namespaces.
+
   a. If you have not already, obtain a Red Hat subscription.
 
   #. Create a `Registry Service Account <https://access.redhat.com/terms-based-registry/>`__.
@@ -92,8 +100,8 @@ content: |
      text editor.
 
   #. Copy the ``registry.redhat.io`` object, and paste another instance
-     of this object into the file. Remember to add a comma after the 
-     first object. Rename the second object 
+     of this object into the file. Remember to add a comma after the
+     first object. Rename the second object
      ``registry.connect.redhat.com``, then save the file:
 
      .. code-block:: json
@@ -110,9 +118,10 @@ content: |
           }
         }
 
-  #. Create a ``openshift-pull-secret.yaml`` file with the contents of 
-     the modified ``<account-name>-auth.json`` file as ``stringData`` 
-     named ``.dockerconfigjson``:
+  #. Create an ``openshift-pull-secret.yaml`` file and add the contents
+     of the modified ``<account-name>-auth.json`` file as
+     ``stringData`` named ``.dockerconfigjson`` to the
+     ``openshift-pull-secret.yaml`` secret file.
 
      .. code-block:: yaml
         :emphasize-lines: 4-16
@@ -136,11 +145,11 @@ content: |
         type: kubernetes.io/dockerconfigjson
 
      The value you provide in the ``metadata.name`` field contains
-     the secret name. Provide this value when asked for the 
+     the secret name. Provide this value when asked for the
      ``<openshift-pull-secret>``.
 
   #. Create a |k8s-secret| from the ``openshift-pull-secret.yaml`` 
-     file:
+     file in the same namespace in which you will deploy the |k8s-op-short|.
 
      .. code-block:: sh
 

source/includes/steps-install-prereqs.yaml

@@ -45,8 +45,8 @@ content: |
 
         oc apply -f crds.yaml
   
-  #. Add your ``<openshift-pull-secret>`` to the ``ServiceAccount`` 
-     definitions in the |k8s-op-full| |yaml| file:
+  #. Add your ``<openshift-pull-secret>`` to the ``ServiceAccount``
+     definitions in the |k8s-op-full| |yaml| file.
 
      .. literalinclude:: /includes/openshift-service-accounts.yaml
         :language: yaml

source/includes/steps-openshift-quick-start.yaml

@@ -426,10 +426,14 @@ registry.imagePullSecrets
 .. example::
 
    .. code-block:: yaml
-      :emphasize-lines: 3
+      :emphasize-lines: 7
 
       registry:
-      # The pull secret must be specified
+      # Specify the secret in the ``imagePullSecrets`` setting. If you
+      # use the MongoDB Kubernetes Operator to deploy MongoDB resources
+      # into multiple namespaces, create the secret only in the namespace
+      # where you installed the Operator. The Operator synchronizes
+      # the secret across all watched namespaces.
         imagePullSecrets: <openshift-pull-secret>
 
 registry.initAppDb