(DOCSP-22471) Refactors TLS for OM application database (#1069)

sarahsimpers · web-flow · commit e726a259cd92 · 2022-10-03T11:37:31.000-04:00
* (DOCSP-22471) Refactors TLS for OM application database * Cleanup, adds missing setting in om spec * Includes changes from copy review * Includes change from tech review
diff --git a/config/redirects b/config/redirects
@@ -87,3 +87,7 @@ raw: docs/kubernetes-operator/release-notes -> ${base}/stable/release-notes/
 # v1.15 and earlier
 
 [*-v1.15]: docs/kubernetes-operator/${version}/third-party-integrations -> ${base}/${version}/
+
+# All Versions
+
+[*]: docs/kubernetes-operator/${version}/tutorial/secure-om-with-tls -> ${base}/${version}/tutorial/deploy-om-container
diff --git a/source/includes/prereqs/secure-om-resource.rst b/source/includes/prereqs/secure-om-resource.rst
@@ -1,8 +1,5 @@
-- :doc:`Install the Kubernetes Operator </tutorial/install-k8s-operator>`.
-
-- :ref:`Deploy the Ops Manager application <deploy-om-container>` that
-  you want to secure.
-
+- Complete the :ref:`Prerequisites <om-rsrc-prereqs>`.
+- Read the :ref:`Considerations <om-rsrc-considerations>`.
 - Create one |tls| certificate for the Application
   Database's :term:`replica set`.
 
diff --git a/source/includes/steps-deploy-k8s-opsmgr-https.yaml b/source/includes/steps-deploy-k8s-opsmgr-https.yaml
@@ -5,31 +5,44 @@ inherit:
   file: steps-configure-kubectl-namespace.yaml
   ref: configure-kubectl-namespace
 ---
-title: "Create a secret for your certificates."
+title: "Create secrets for your certificates."
 stepnum: 2
 ref: create-cert-secret
 content: |
 
-   Once you have your |tls| certificate and Private Key, run the 
-   following command to store the certificates in a |k8s-secret|:
+  .. include:: /includes/facts/fact-if-use-vault.rst
+  .. include:: /includes/facts/fact-learn-more-secret-storage.rst
 
-   .. code-block:: sh
+  a. Once you have your |tls| certificates and private keys, run the 
+     following command to create a |k8s-secret| that stores |onprem|\'s
+     |tls| certificate:
+
+     .. code-block:: sh
+
+        kubectl create secret tls <prefix>-<metadata.name>-cert \
+          --cert=<om-tls-cert> \
+          --key=<om-tls-key>
+
+  b. Run the following command to create a new |k8s-secret| that stores
+     the application database's |tls| certificate:
 
-      kubectl create secret tls <prefix>-<metadata.name>-cert \
-       --cert=<om-tls-cert> \
-       --key=<om-tls-key>
+     .. code-block:: sh
+
+        kubectl create secret tls <prefix>-<metadata.name>-db-cert \
+          --cert=<appdb-tls-cert> \
+          --key=<appdb-tls-key>
 
-   .. include:: /includes/facts/fact-if-use-vault.rst
 ---
-title: "If necessary, validate your TLS Certificate."
+title: "If necessary, validate your TLS certificates."
 stepnum: 3
 ref: validate-tls-cert
 content: |
 
-  If your |tls| certificate is signed by a Custom Certificate
+  If your |onprem| |tls| certificate or your application database 
+  |tls| certificate is signed by a Custom Certificate
   Authority, you must provide a :abbr:`CA (Certificate Authority)`
-  certificate to validate the |tls| certificate. To validate the
-  |tls| certificate, create a |k8s-configmap| to hold the
+  certificate to validate the |tls| certificate(s). To validate the
+  |tls| certificate(s), create a |k8s-configmap| to hold the
   :abbr:`CA (Certificate Authority)` certificate:
 
   .. warning::
@@ -41,10 +54,15 @@ content: |
 
   .. important::
 
-     The |k8s-op-short| requires that the certificate is named
-     ``mms-ca.crt`` in the ConfigMap.
+     The |k8s-op-short| requires that:
+     
+     - Your |onprem| certificate is named ``mms-ca.crt`` in the
+       ConfigMap.
+     - Your application database certficate is named ``ca-pem`` in
+       the ConfigMap.
 
-  a. Obtain the entire |tls| certificate chain from
+  a. Obtain the entire |tls| certificate chain for both |onprem| and
+     the application database from
      ``downloads.mongodb.com``. The following ``openssl`` command
      outputs each certificate in the chain to your current working
      directory, in ``.crt`` format:
@@ -55,33 +73,48 @@ content: |
         -connect downloads.mongodb.com:443 -servername downloads.mongodb.com < /dev/null \
         | awk '/BEGIN/,/END/{ if(/BEGIN/){a++}; out="cert"a".crt"; print >out}'
 
-  #. Concatenate your |certauth|\'s certificate file with the
-     entire |tls| certificate chain from ``downloads.mongodb.com`` that
+  #. Concatenate your |certauth|\'s certificate file for |onprem|
+     with the entire |tls| certificate chain from 
+     ``downloads.mongodb.com`` that
      you obtained in the previous step:
 
      .. code-block:: sh
 
         cat cert1.crt cert2.crt cert3.crt cert4.crt  >> mms-ca.crt
-  #. Create the |k8s-configmap|:
+  #. Concatenate your |certauth|\'s certificate file for the application
+     database with the entire |tls| certificate chain from 
+     ``downloads.mongodb.com`` that
+     you obtained in the previous step:
+
+     .. code-block:: sh
+
+        cat cert1.crt cert2.crt cert3.crt cert4.crt  >> ca-pem
+  #. Create the |k8s-configmap| for |onprem|:
 
      .. code-block:: sh
 
         kubectl create configmap om-http-cert-ca --from-file="mms-ca.crt"
 
+  #. Create the |k8s-configmap| for the application database:
+
+     .. code-block:: sh
+
+        kubectl create configmap ca --from-file="ca-pem"
+
 ---
 title: "Copy the following example |onprem| |k8s| |k8s-obj|."
 stepnum: 4
 level: 4
 ref: copy-k8s-example
 content: |
 
-   Change the highlighted settings to match your desired
-   |onprem| configuration.
+  Change the highlighted settings to match your desired
+  |onprem| and application database configuration.
 
-   .. literalinclude:: /reference/k8s/example-opsmgr-https.yaml
-      :language: yaml
-      :linenos:
-      :emphasize-lines: 5,7-11,14-23,25-27
+  .. literalinclude:: /reference/k8s/example-opsmgr-https.yaml
+     :language: yaml
+     :linenos:
+     :emphasize-lines: 5,7-11,14-23,25-37
 ---
 title: "Open your preferred text editor and paste the |k8s-obj| specification into a new text file."
 stepnum: 5
@@ -162,12 +195,14 @@ content: |
           | ``.tls``
           | ``.``:opsmgrkube:`~spec.security.tls.ca`
         - string
-        - Name of the |k8s-configmap| you created to verify |tls|
+        - Name of the |k8s-configmap| you created to verify your
+          |onprem| |tls|
           certificates signed using a Custom Certificate Authority.
 
           .. important::
 
-             This field is required if you signed your |tls|
+             This field is required if you signed your 
+             |onprem| |tls|
              certificates using a Custom Certificate Authority.
 
         - ``om-http-cert-ca``
@@ -220,6 +255,41 @@ content: |
 
         - .. include:: /includes/facts/fact-which-appdb-version.rst
 
+      * - | ``spec``
+          | ``.applicationDatabase``
+          | ``.security``
+          | ``.``:opsmgrkube:`~spec.applicationDatabase.security.certsSecretPrefix`
+        - string
+        - *Required*.
+        
+          Text to prefix to the name of the secret that contains
+          the application database's |tls| certificates.
+        - ``appdb-prod``
+
+      * - | ``spec``
+          | ``.applicationDatabase``
+          | ``.security``
+          | ``.tls``
+          | ``.``:opsmgrkube:`~spec.applicationDatabase.security.tls.ca`
+        - string
+        - Name of the |k8s-configmap| you created to verify your
+          application database |tls|
+          certificates signed using a Custom Certificate Authority.
+
+          .. important::
+
+             This field is required if you signed your 
+             application database |tls|
+             certificates using a Custom Certificate Authority.
+
+        - ``ca``
+
+   .. note::
+
+      The |k8s-op-short| mounts the |certauth| you add using the
+      :opsmgrkube:`spec.applicationDatabase.security.tls.ca` setting to
+      both the |onprem| and the Application Database pods.
+
 ---
 title: "Configure Backup settings"
 stepnum: 7
@@ -696,4 +766,5 @@ content: |
 
   See :doc:`/reference/troubleshooting` for information about the
   resource deployment statuses.
+
 ...
diff --git a/source/includes/steps-secure-om-appdb.yaml b/source/includes/steps-secure-om-appdb.yaml
@@ -1,9 +1,3 @@
----
-ref: configure-kubectl-standalone
-stepnum: 1
-inherit:
-  file: steps-configure-kubectl-namespace.yaml
-  ref: configure-kubectl-namespace
 --- 
 ref: create-om-appdb-secret
 stepnum: 2
diff --git a/source/om-resources.txt b/source/om-resources.txt
@@ -16,7 +16,9 @@ Deploy and Configure Ops Manager Resources
   prerequisites.
 
 :ref:`deploy-om-container`
-  Use the |k8s-op-short| to deploy an |onprem| instance.
+  Use the |k8s-op-short| to deploy an |onprem| instance and encrypt the
+  connection between the application database's replica set
+  members.
 
 :ref:`deploy-om-container-remote-mode`
   Use the |k8s-op-short| to configure |onprem| to operate in 
@@ -49,5 +51,4 @@ Deploy and Configure Ops Manager Resources
       /tutorial/deploy-om-container
       /tutorial/deploy-om-container-remote-mode
       /tutorial/deploy-om-container-local-mode
-      /tutorial/secure-om-with-tls
       /tutorial/configure-om-queryable-backups
diff --git a/source/reference/k8s-operator-om-specification.txt b/source/reference/k8s-operator-om-specification.txt
@@ -176,6 +176,14 @@ Optional |onprem| Resource Settings
 
    The default value is ``password``.
 
+.. opsmgrkube:: spec.applicationDatabase.security.certsSecretPrefix
+
+   *Type*: string
+
+   Text to prefix to the name of the secret that contains the
+   application database's |tls| certificate. Name the secret
+   ``<prefix>-<metadata.name>-db-cert``.
+
 .. opsmgrkube:: spec.applicationDatabase.security.tls.ca
 
    *Type*: string
@@ -1150,8 +1158,9 @@ snapshots, and secure connections to |s3| with |tls| using keys
 issued by custom |certauth|. 
 
 To configure custom CA keys, use the ConfigMap with which you 
-configured |tls| for your application database as described in 
-`Create a ConfigMap That Contains the Certificate Authority <https://www.mongodb.com/docs/kubernetes-operator/stable/tutorial/secure-om-with-tls/#optional-create-a-configmap-that-contains-the-certificate-authority>`__.
+configured |tls| for your application database as described on
+the :guilabel:`TLS-Encrypted Connection (HTTPS)` tab of 
+:ref:`deploy-om-container`.
 Set :opsmgrkube:`spec.applicationDatabase.security.tls.ca` to this ConfigMap.
 
 You can use |tls| for both |s3| and your application database, or for 
diff --git a/source/reference/k8s/example-opsmgr-https.yaml b/source/reference/k8s/example-opsmgr-https.yaml
@@ -17,13 +17,23 @@ spec:
                                   # the name of the secret that contains
                                   # Ops Manager's TLS certificate.
       tls:
-        ca: <om-http-cert-ca>  # Optional. Name of the ConfigMap file
+        ca: "om-http-cert-ca"  # Optional. Name of the ConfigMap file
                                # containing the certificate authority that
                                # signs the certificates used by the Ops
                                # Manager custom resource.
 
   applicationDatabase:
     members: 3
-    version: <mongodbversion>
+    version: "4.4.0-ent"
+    security:
+      certsSecretPrefix: <prefix> # Required. Text to prefix to the 
+                                  # name of the secret that contains the Application
+                                  # Database's TLS certificate. Name the secret 
+                                  # <prefix>-<metadata.name>-db-cert.
+      tls:
+        ca: "appdb-ca" # Optional. Name of the ConfigMap file
+                       # containing the certicate authority that
+                       # signs the certificates used by the
+                       # application database.
 
 ...
diff --git a/source/tutorial/deploy-om-container.txt b/source/tutorial/deploy-om-container.txt
@@ -1,6 +1,7 @@
 :noprevnext:
 
 .. _deploy-om-container:
+.. _secure-om-db-tls:
 
 ===========================
 Deploy an |onprem| Resource
@@ -18,40 +19,68 @@ Deploy an |onprem| Resource
 
 You can deploy |onprem| in a container with the |k8s-op-short|.
 
-Prerequisites and Considerations
---------------------------------
+Considerations
+--------------
 
-.. include:: /includes/deploy-om-prereqs.rst
+When you configure your |onprem| deployment, you must choose whether to run connections over |http| or |https|.
 
-Considerations for |onprem| Deployments over HTTPS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following |http| procedure: 
 
-You can configure your deployed |onprem| resource to run over |https|,
-rather than |http|. A full description of TLS, PKI (Public Key
-Infrastructure) certificates, and Certificate Authority is beyond the
-scope of this tutorial. This tutorial assumes prior knowledge of TLS/SSL
-as well as access to valid certificates.
+- Doesn't encrypt connections to/from the |onprem| application.
+- Doesn't encrypt connections between the
+  application database's replica set members.
+- Has fewer setup requirements.
 
-When running over |https|, |onprem| runs on port ``8443`` by default.
+The following |https| procedure:
+ 
+- Establishes |tls|-encrypted connections to/from the |onprem|
+  application.
+- Establishes |tls|-encrypted connections between the application
+  database's replica set members.
+- Requires valid certificates for |tls| encryption.
+
+When running over |https|, |onprem| runs on port ``8443`` by
+default.
+
+Select the appropriate tab based on whether you want to encrypt
+your |onprem| and application database connections with |tls|.
+
+.. tabs::
+
+   .. tab:: Non-Encrypted Connections (HTTP)
+      :tabid: http
+
+      Prerequisites
+      -------------
+
+      .. include:: /includes/deploy-om-prereqs.rst
+
+   .. tab:: TLS-Encrypted Connections (HTTPS)
+      :tabid: https
+
+      Prerequisites
+      -------------
+
+      .. include:: /includes/prereqs/secure-om-resource.rst
 
 Procedure
 ---------
 
-Select the appropriate tab based on whether you want your |onprem|
-instance to run over |http| or |https|:
-
 .. tabs::
+   :hidden:
+
+   .. tab:: Non-Encrypted Connection (HTTP)
+      :tabid: http
 
-   tabs:
+      Follow these steps to deploy the |onprem| resource to run over
+      |http|:
 
-      - id: http
-        name: HTTP
-        content: |
+      .. include:: /includes/steps/deploy-k8s-opsmgr-http.rst
 
-           .. include:: /includes/steps/deploy-k8s-opsmgr-http.rst
+   .. tab:: TLS-Encrypted Connection (HTTPS)
+      :tabid: https
 
-      - id: https
-        name: HTTPS
-        content: |
+      Follow these steps to deploy the |onprem| resource to run over 
+      |https| and secure the application database using |tls|.
         
-           .. include:: /includes/steps/deploy-k8s-opsmgr-https.rst
+      .. include:: /includes/steps/deploy-k8s-opsmgr-https.rst
diff --git a/source/tutorial/secure-om-with-tls.txt b/source/tutorial/secure-om-with-tls.txt
