(DOCSP-12132): concatenate download.mongodb.com + custom ca certs (#379)

* (DOCSP-12132): concatenate download.mongodb.com + custom ca certs

* (DOCSP-12132): copy review feedback

Author: jwilliams-mongo

source/includes/admonitions/warning-concatenate-download-certs.rst

@@ -0,0 +1,6 @@
+.. warning::
+
+   You must concatenate your custom |certauth| file and the entire
+   |tls| certificate chain from ``downloads.mongodb.com`` to prevent
+   |onprem| from becoming inoperable if the application database
+   restarts.

source/includes/options-k8s-shared.yaml

@@ -523,7 +523,7 @@ type: string
 directive: setting
 optional: true
 description: |
-  Provide the name of the |k8s-secret| that store the |certauth|.
+  Provide the name of the |k8s-secret| that stores the |certauth|.
 ---
 program: _shared
 name: spec.security.authentication

source/includes/steps-deploy-k8s-opsmgr-https.yaml

@@ -41,20 +41,51 @@ stepnum: 4
 ref: validate-tls-cert
 content: |
 
-   If your |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
-   :abbr:`CA (Certificate Authority)` certificate:
+  If your |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
+  :abbr:`CA (Certificate Authority)` certificate:
 
-   .. code-block:: sh
+  .. warning::
 
-      kubectl create configmap om-http-cert-ca --from-file="mms-ca.crt"
+     You must concatenate your custom |certauth| file and the entire
+     |tls| certificate chain from ``downloads.mongodb.com`` to prevent
+     |onprem| from becoming inoperable if the application database
+     restarts.
 
-   .. important::
+  .. important::
 
      The |k8s-op-short| requires that the certificate is named
      ``mms-ca.crt`` in the ConfigMap.
+
+  a. Obtain the entire |tls| certificate chain from
+     ``downloads.mongodb.com``. The following ``openssl`` command
+     outputs each certificate in the chain to your current working
+     directory, in ``.crt`` format:
+
+     .. using path to openssl to preempt macOS libressl issues
+
+     .. code-block:: sh
+
+        /usr/local/opt/openssl/bin/openssl s_client -showcerts -verify 2 \ 
+        -connect downloads.mongodb.com:443 < /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
+     you obtained in the previous step:
+
+     .. code-block:: sh
+
+        cat cert1.crt cert2.crt cert3.crt cert4.crt  >> ca-pem
+
+  #. Create the |k8s-configmap|:
+
+     .. code-block:: sh
+
+        kubectl create configmap om-http-cert-ca --from-file="mms-ca.crt"
+
 ---
 title: "Copy the following example |onprem| |k8s| |k8s-obj|."
 stepnum: 5

source/includes/steps-source-deploy-om-resource.yaml

@@ -38,27 +38,53 @@ title: "Create a ConfigMap containing the Certificate Authority."
 optional: true
 content: |
 
-  You need to provide a |certauth| certificate when the |certauth| that
+  You must provide a |certauth| certificate when the |certauth| that
   signed the certificates might be not "recognized" as an official
   authority. Recognized and valid certificates can be created with
   `cert-manager <https://cert-manager.io/docs/>`__ or `HashiCorp Vault
   <https://www.vaultproject.io/>`__.
 
-  If you signed the certificates using a |k8s| certicate management
+  If you signed the certificates using a |k8s| certificate management
   tool like `cert-manager <https://cert-manager.io/docs/>`__ or
   `HashiCorp Vault <https://www.vaultproject.io/>`__, you must create a
   |k8s-configmap| containing the |certauth|\'s certificate file.
 
   If you output the certificate as a file, name this file ``ca-pem``.
   This simplifies creating the |k8s-configmap|.
 
-  .. code-block:: sh
+  .. include:: /includes/admonitions/warning-concatenate-download-certs.rst
+
+  a. Obtain the entire |tls| certificate chain from
+     ``downloads.mongodb.com``. The following ``openssl`` command
+     outputs each certificate in the chain to your current working
+     directory, in ``.crt`` format:
+
+     .. using path to openssl to preempt macOS libressl issues
+
+     .. code-block:: sh
+
+        /usr/local/opt/openssl/bin/openssl s_client -showcerts -verify 2 \ 
+        -connect downloads.mongodb.com:443 < /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
+     you obtained in the previous step:
+
+     .. code-block:: sh
+
+        cat cert1.crt cert2.crt cert3.crt cert4.crt  >> ca-pem
+
+  #. Create the |k8s-configmap|:
+
+     .. code-block:: sh
 
-     kubectl create configmap appdb-ca --from-file=ca-pem
+        kubectl create configmap ca --from-file="ca-pem"
 
-  This creates a |k8s-configmap| named ``appdb-ca``. This
+  This creates a |k8s-configmap| named ``ca``. This
   |k8s-configmap| contains one entry called ``ca-pem`` with the
-  contents of the |certauth| file.
+  contents of the |certauth| file and the certificate chain for
+  ``downloads.mongodb.com``.
 
 ---
 stepnum: 0

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

@@ -200,6 +200,8 @@ Optional |onprem| Resource Settings
    - |onprem| uses to communicate with the application database replica
      set.
 
+  .. include:: /includes/admonitions/warning-concatenate-download-certs.rst
+
 .. opsmgrkube:: spec.applicationDatabase.security.tls.secretRef.name
 
    *Type*: string
@@ -833,11 +835,16 @@ Optional |onprem| Resource Settings
       :opsmgrkube:`spec.security.tls.ca` is required if you use a Custom
       Certificate Authority to sign your |onprem| |tls| certificates.
 
+      The |k8s-op-short| requires that the certificate is named
+      ``mms-ca.crt`` in the ConfigMap.
+
    This |certauth| signs the certificates that:
 
    - clients use to connect to the |application|, and
    - agents in the application database |k8s-pods| use to communicate
-     with |onprem|. 
+     with |onprem|.
+
+   .. include:: /includes/admonitions/warning-concatenate-download-certs.rst
 
 .. opsmgrkube:: spec.security.tls.secretRef.name