(DOCSP-20210) Queryable backups updates (#834)

* (DOCSP-20210) Queryable backups updates

* Edits, ready for a review

* Edits, ready for a review

* Edits, ready for a review

* Edits, ready for a review

* Tech review

* 2nd round of tech review

* edits

* Tech review. Set the default to false

* Tech review

* tech review

Author: JuliaMongo

source/includes/steps-configure-om-queryable-backups.yaml

@@ -11,24 +11,22 @@ ref: create-pem-file
 title: "Create the PEM file for backups."
 content: |
     
-    Create the :opsmgr:`queryable.pem
-    </reference/configuration/#brs.queryable.pem>`
+    Create the :opsmgr:`Ops Manager queryable.pem </reference/configuration/#brs.queryable.pem>`
     file that you will use for accessing and querying backups based on
     your deployment's |tls| requirements. The PEM file contains a public
     key certificate and its associated private key that are needed to
-    access and run queries on |onprem| backup snapshots.
+    access and run queries on backup snapshots in |onprem|.
 
     To learn more about the PEM file's requirements, see
-    :opsmgr:`Authorization and Authentication Requirements
+    :opsmgr:`Authorization and Authentication Requirements in Ops Manager
     </tutorial/query-backup/#authentication-and-authorization>`.
-
 ---
 stepnum: 3
 level: 4
 ref: create-queryable-pem-secret
-title: "Create a Secret containing the PEM file."
+title: "Create a secret containing the PEM file."
 content: |
-  Run the following command to create a Secret with the
+  Run the following command to create a secret with the
   :opsmgr:`queryable.pem </reference/configuration/#brs.queryable.pem>`
   file that you created in the previous step:
 
@@ -40,25 +38,19 @@ content: |
 
   .. include:: /includes/facts/fact-learn-more-secret-storage.rst
 ---
-title: "Mount the Secret as a volume that |onprem| custom objects will use."
+title: "Configure |onprem| custom resource to use the secret."
 stepnum: 4
 level: 4
 ref: mount-pem-secret
 content: |
 
-  The |k8s-op-short| must be able to access the :opsmgr:`queryable.pem
-  </reference/configuration/#brs.queryable.pem>` file in the mount point
-  for the persistent volume in the Pod's container for |onprem|.
-
-  To mount the Secret, use one of these methods:
-
-  - Configure volumes using ``volumeClaimTemplates`` and specify the
-    location for the :opsmgr:`queryable.pem
-    </reference/configuration/#brs.queryable.pem>` file:
+  Configure :opsmgrkube:`spec.backup.queryableBackupSecretRef.name` to
+  reference the :opsmgr:`queryable.pem </reference/configuration/#brs.queryable.pem>`
+  secret.
 
-    .. code-block:: yaml
-       :linenos:
-       :emphasize-lines: 9-35
+  .. code-block:: yaml
+     :linenos:
+     :emphasize-lines: 8-12
 
        apiVersion: mongodb.com/v1
        kind: MongoDBOpsManager
@@ -68,74 +60,10 @@ content: |
          replicas: 1
          version: 5.0.0
          adminCredentials: ops-manager-admin-secret
-         configuration:
-           mms.fromEmailAddr: "[email protected]"
-           brs.queryable.pem: "/certs/queryable.pem"
- 
-         statefulSet:
-           spec:
-            # the Persistent Volume Claim is created for each Ops Manager Pod
-            volumeClaimTemplates:
-              - metadata:
-                  name: queryable-volume
-                spec:
-                  accessModes: [ "ReadWriteOnce" ]
-                  storageClassName: <your_storage_class_name>
-                  resources:
-                    requests:
-                       storage: 1G
-            template:
-              spec:
-                containers:
-                  - name: mongodb-ops-manager
-                  volumeMounts:
-                       - name: queryable-volume
-                       - mountPath: /certs
-                volumes:
-                  - name: queryable-pem
-                  secret:
-                   secretName: queryable-pem
-
-         applicationDatabase:
-            members: 3
-            version: 4.2.6-ent
-
-  - Configure volumes without using ``volumeClaimTemplates`` and specify
-    the location for the :opsmgr:`queryable.pem
-    </reference/configuration/#brs.queryable.pem>` file:
-
-    .. code-block:: yaml
-       :linenos:
-       :emphasize-lines: 9-24
-
-       apiVersion: mongodb.com/v1
-        kind: MongoDBOpsManager
-        metadata:
-          name: ops-manager
-       spec:
-          replicas: 1
-          version: 5.0.0
-          adminCredentials: ops-manager-admin-secret
-          configuration:
-            brs.queryable.pem: "/certs/queryable.pem"
-            mms.fromEmailAddr: "[email protected]"
-          statefulSet:
-            template:
-              spec:
-                containers:
-                  - name: mongodb-ops-manager
-                  volumeMounts:
-                   - name: queryable-volume
-                   - mountPath: /certs/
-                   
-                volumes:
-                  - name: queryable-pem
-                  secret:
-                    secretName: queryable-pem
- 
-       applicationDatabase:
-         members: 3
-         version: 4.2.6-ent
+         backup:
+           enabled: true
+           queryableBackupSecretRef:
+             name: om-queryable-pem
 
 ---
 title: "Save your |onprem| config file."

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

@@ -2,7 +2,7 @@
 stepnum: 1
 level: 4
 ref: mc-openssl-generate-certs-csrs
-title: "Use OpenSSL to generate CA certificates, CSRs, and server certificates."
+title: "Use OpenSSL to generate CA certificates, |csrs|, and server certificates."
 content: |
 
     a. (Optional). If you don't have a |certauth| key and root certificate for your
@@ -29,13 +29,13 @@ content: |
              -extensions v3_ca \
              -out ./certs/ca.crt
 
-    #. For each member cluster, generate a key for the Certificate Signing Request (CSR) with `genrsa <https://www.openssl.org/docs/man3.0/man1/genrsa.html>`__:
+    #. For each member cluster, generate a key for the |csr| with `genrsa <https://www.openssl.org/docs/man3.0/man1/genrsa.html>`__:
 
        .. code-block:: sh
 
           openssl genrsa -out ./certs/{cluster-X-cert-key}.key 2048
 
-    #. For each member cluster, generate a CSR using its key with `openssl req <https://www.openssl.org/docs/man3.0/man1/openssl-req.html>`__.
+    #. For each member cluster, generate a |csr| using its key with `openssl req <https://www.openssl.org/docs/man3.0/man1/openssl-req.html>`__.
 
        .. code-block:: sh
 
@@ -45,7 +45,7 @@ content: |
              -out ./certs/{cluster-X-cert-signing}.csr
 
     #. For each member cluster, using the generated CA key, root
-       certificate, and the CSR, generate a server certificate. The
+       certificate, and the |csr|, generate a server certificate. The
        following procedure uses `openssl req <https://www.openssl.org/docs/man3.0/man1/openssl-req.html>`__
        in combination with ``bash -extfile`` and ``printf`` to first
        contstruct a ``subjectAltName`` parameter, and then inject it

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

@@ -23,8 +23,7 @@ content: |
        tool generates a self-signed |certauth| key and root certificate.
      - The MongoDB multi-cluster resource name.
      - The central cluster name and namespace.
-     - The country, state, and name of the organization for the
-       Certificate Signing Request (CSR).
+     - The country, state, and name of the organization for the |csr|.
 
      The following example shows how to run the tool if you have a |certauth|
      key and root certificate:

source/multi-cluster-secure.txt

@@ -25,7 +25,7 @@ to generate server certificates for each member cluster and then updates
 the |k8s-op-short| configuration on each member cluster.
 
 Alternatively, you can :ref:`run OpenSSL commands <multi-cluster-tls-openssl>`
-directly on each member cluster to generate server certificates and CSRs,
+directly on each member cluster to generate server certificates and |csrs|,
 and then update the |k8s-op-short| configuration on each member cluster.
 
 .. _multi-cluster-security-prereqs:
@@ -52,9 +52,9 @@ The tool runs OpenSSL commands and takes the following actions:
 - On each member cluster, uses a |certauth| key and root certificate that
   you specify, or generates a new self-signed |certauth| certificate and
   key if you don't specify a |certauth| key and root certificate.
-- Generates each cluster's Certificate Signing Request (CSR) and server
-  certificates for each member cluster's host.
-- Based on these certificates and a CSR, creates a cluster certificate
+- Generates each cluster's |csr| and server certificates for each member
+  cluster's host.
+- Based on these certificates and a |csr|, creates a cluster certificate
   secret for each member cluster. Each cluster certificate secret consists
   of all generated server certificates and each member cluster host's
   secret key. The host's secret key contains the server certificate
@@ -74,8 +74,8 @@ Configure TLS with OpenSSL
 In this procedure you:
 
 - Use OpenSSL to generate member cluster's |certauth| root certificates
-  and CSRs, and server certificates for each member cluster's host.
-- Based on these certificates and CSRs, use OpenSSL to create the member
+  and |csrs|, and server certificates for each member cluster's host.
+- Based on these certificates and |csrs|, use OpenSSL to create the member
   cluster certificate secrets. Each cluster certificate secret consists
   of all generated server certificates and each member cluster host's
   secret key. The host's secret key contains the server certificate

source/reference/k8s-operator-om-specification.txt

@@ -502,6 +502,18 @@ Optional |onprem| Resource Settings
    :manual:`dbAdminAnyDatabase
    </reference/built-in-roles/#dbAdminAnyDatabase>` roles.
 
+.. opsmgrkube:: spec.backup.queryableBackupSecretRef.name
+
+   *Type*: string
+
+   Name of the secret that contains the :opsmgr:`queryable.pem </reference/configuration/#brs.queryable.pem>`
+   file from |onprem| that you will use for accessing and querying backups
+   based on your deployment's |tls| requirements.The PEM file contains
+   a public key certificate and its associated private key that are needed
+   to access and run queries on backup snapshots in |onprem|.
+   To query backups, specify the value for this parameter. If not set,
+   backups are not affected, but you can't query them.
+
 .. opsmgrkube:: spec.backup.statefulSet.spec
 
    *Type*: collection

source/reference/k8s/example-openshift-replica-set.yaml

@@ -21,9 +21,9 @@ spec:
       enabled: true
       modes: ["SCRAM","X509"]
   connectivity:
-    # The "localhost" routes are there just to make sure the localhost 
-    # TLS SAN is created in the CSR, per OpenShift route requirements.
-    # "ocroute" is the configured route in openshift
+    # The "localhost" routes are included to enable the creation of localhost
+    # TLS SAN in the CSR, per OpenShift route requirements.
+    # "ocroute" is the configured route in OpenShift.
     replicaSetHorizons:
       - "ocroute": "my-external-0.{redacted}:443"
         "localhost": "localhost:27017"

source/tutorial/configure-om-queryable-backups.txt

@@ -22,40 +22,27 @@ for |onprem| resources that you deploy in the |k8s-op-short|.
 .. note:: In the |onprem| documentation, queryable backups are also
           referred to as queryable snapshots, or queryable restores.
 
-Queryable backups allow you to :opsmgr:`run queries
-</tutorial/query-backup/#query-backup-handle-tls-authentication-manually>`
-on specific backup snapsnots from your |onprem| resources. Querying
-|onprem| backups helps you compare data from different snapshots
-and identify the best snapshot to use for :opsmgr:`restoring data
-</tutorial/restore-single-database/#restore-from-queryable-backup>`.
+Queryable backups allow you to :opsmgr:`run queries </tutorial/query-backup/#query-backup-handle-tls-authentication-manually>`
+on specific backup snapsnots from your |onprem| resources. Querying |onprem|
+backups helps you compare data from different snapshots and identify the
+best snapshot to use for :opsmgr:`restoring data </tutorial/restore-single-database/#restore-from-queryable-backup>`.
 
 In the following procedure you:
 
-- Create the :opsmgr:`queryable.pem
-  </reference/configuration/#brs.queryable.pem>` file that holds the
-  certificatesfor accessing the backup snapshots that you intend to query.
-
-- Create the secret containing the :opsmgr:`queryable.pem
-  </reference/configuration/#brs.queryable.pem>` file.
-
-- Configure a persistent volume that is attached to the |onprem|
-  |k8s| Pod in the |k8s-op-short|.
-
-- Specify the mount point for the secret in  the persistent volume's
-  configuration.
-
+- Create the :opsmgr:`queryable.pem </reference/configuration/#brs.queryable.pem>`
+  file that holds the certificates for accessing the backup snapshots that you intend to query.
+- Create the secret containing the :opsmgr:`queryable.pem </reference/configuration/#brs.queryable.pem>` file.
+- Configure an |onprem| custom resource to use the secret for queryable backups.
 - Save the |onprem| custom resource configuration and apply it.
 
-Once the |k8s-op-short| deploys the updated configuration for the
-|onprem| custom resource, |onprem| can read the Secret from the
-specified location in the :opsmgr:`queryable.pem
-</reference/configuration/#brs.queryable.pem>` parameter in |onprem|.
-You can now access the backup snapshots and run queries on them.
+Once the |k8s-op-short| deploys the updated configuration for its custom
+resource, |onprem| can read the secret from the :opsmgrkube:`spec.backup.queryableBackupSecretRef.name`
+parameter. You can now access the backup snapshots and run queries on them.
 
 Prerequisites
 -------------
 
-Before you configure queryable backups, complete the following:
+Before you configure queryable backups, complete the following tasks:
 
 - :doc:`Install the Kubernetes Operator </tutorial/install-k8s-operator>`.
 
@@ -69,8 +56,5 @@ Procedure
 
 .. include:: /includes/steps/configure-om-queryable-backups.rst
 
-After you configure queryable backups, you can :opsmgr:`query them
-</tutorial/query-backup/>` to select the best backup snapshot to use for
-:opsmgr:`restoring data
-</tutorial/restore-single-database/#restore-from-queryable-backup>`.
-
+After you configure queryable backups, you can :opsmgr:`query them </tutorial/query-backup/>`
+to select the best backup snapshot to use for :opsmgr:`restoring data </tutorial/restore-single-database/#restore-from-queryable-backup>`.

source/tutorial/om-arch.txt

@@ -157,7 +157,7 @@ changes to the ``MongoDBOpsManager`` |k8s-crd|.
 .. _om-arch-steps:
 
 1. The |k8s-op-short| creates or updates the
-   ``<om_resource_name>-db-config`` Secret. This secret contains
+   ``<om_resource_name>-db-config`` secret. This secret contains
    the configurations that the {+mdbagent+} uses to start the
    Application Database replica set.
 
@@ -168,7 +168,7 @@ changes to the ``MongoDBOpsManager`` |k8s-crd|.
    - Each Pod runs one {+mdbagent+} instance. Each {+mdbagent+} starts a
      |mongod| instance on its Pod.
    - The |k8s-op-short| mounts the ``<om_resource_name>-db-config``
-     Secret to each Pod. The {+mdbagent+} uses this secret to
+     secret to each Pod. The {+mdbagent+} uses this secret to
      configure the Application Database replica set.
 
 3. The |k8s-op-short| creates or updates the ``<om_resource_name>``
@@ -191,7 +191,7 @@ changes to the ``MongoDBOpsManager`` |k8s-crd|.
 
 4. The |k8s-op-short| invokes |onprem| APIs to create an admin user.
    The |k8s-op-short| saves this admin user's credentials in the
-   ``<om_resource_name>-admin-key`` Secret. The |k8s-op-short|
+   ``<om_resource_name>-admin-key`` secret. The |k8s-op-short|
    uses these credentials for all other |onprem| API invocations.
 
    .. note::