(DOCSP-14366) TLS options adding/deprecating (#680)

* (DOCSP-14366) Initial commit. To be continued

* Initial adding of information, after fixing the ticket's requirements

* Fixing warnings in the build

* Fixing syntax warnings

* Added copy review from JW, and updated procedures for sharded clusters

* Trying to fix the build warnings

* Trying to fix syntax warnings

* Fixed the build warnings
gaa
gst

* Found more issues

* Remove a typo

* Fxing yet more issues

* Fixing the example

* This will never end

* fixing warnings

* fixing code highlighting

* Friday portion of review, addressed additional issues that are not part of the initial ticket but are bugs in the docs, see comments in the pr

* Went over examples to see that tls.ca is added to appdb security settings, and that secretRef.name is added to ops manager security settings as it is still used

* Monday copy review

* Making sure all names that changed are updated with prefix and -cert. Keeping other names as they are.

* Copy edits and cleanup

* Copy edits

* Copy edits. Ready for Cian review

* A few typos, a few clarifications, and reverting some metadata name to prefix changes from prev commit

Author: JuliaMongo

source/includes/admonitions/deprecate-cert-generation.rst

@@ -1,8 +1,7 @@
-.. admonition:: Deprecation Notice
-   :class: warning
+.. important:: Deprecation Notice
 
    Automatically generating |tls| certificates with the |k8s-op-short|
    is deprecated and will be removed in a future release.
 
-   You must provide certificates from your own CA, as described in the 
+   You must provide certificates from your own CA, as described in the
    following procedures, for production environments.

source/includes/admonitions/deprecate-secret-ref-name.rst

@@ -0,0 +1,15 @@
+.. important:: Deprecation Notice
+
+   The :opsmgrkube:`spec.security.tls.secretRef.name` field is deprecated
+   for the MongoDB resources and for the application database in the
+   |onprem| resources. You can continue using :opsmgrkube:`spec.security.tls.secretRef.name`
+   for the |onprem| resources other than the application database.
+   
+   This field will remain in future releases to maintain backwards
+   compatibility. Instead of the deprecated field, use:
+
+   - :opsmgrkube:`spec.applicationDatabase.security.tls.secretRef.prefix`,
+     for the application database in your |onprem| resources.
+   - :setting:`spec.security.tls.secretRef.prefix`, for MongoDB resources.
+
+   

source/includes/code-examples/yaml-files/example-opsmgr.yaml

@@ -11,16 +11,30 @@ spec:
   configuration:
     mms.fromEmailAddr: [email protected]
     mms.security.allowCORS: "false"
+  security:
+    tls:
+      ca: "opsmgr-ca" # Optional. Name of the ConfigMap file
+                      # containing the certicate authority that
+                      # signs the certificates that the Ops Manager
+                      # resource uses.
+      secretRef:
+        name: "opsmgr" # Optional. Name of the secret for the
+                       # Ops Manager custom  resource.
   applicationDatabase:
     members: 3
     version: "4.2.11-ent"
-    security:
-      tls:
-        ca: "appdb-ca" # Optional. Name of the ConfigMap file
-                       # containing the certicate authority that
-                       # signs the certificates that the application
-                       # database uses.
-        secretRef:
-          name: "appdb-certs" # Name of the Secret object
+      security:
+        tls:
+          ca: "appdb-ca" # Optional. Name of the ConfigMap file
+                         # containing the certicate authority that
+                         # signs the certificates used by the
+                         # application database.
+          secretRef:
+            prefix: "appdb" # Optional. The ``<prefix>`` of the
+                            # application database secret's name that
+                            # contains your MongoDB deployment's TLS
+                            # certificates. If you omit the prefix, this
+                            # setting defaults to the value of
+                            # metadata.name of the Ops Manager custom resource.
 ...
 END-secure-appdb-full

source/includes/code-examples/yaml-files/example-replica-set.yaml

@@ -412,6 +412,8 @@ spec:
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
 ...
 END-tls-replset-full-custom
 
@@ -438,6 +440,8 @@ START-tls-replset-lower-custom
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
 ...
 END-tls-replset-lower-custom
 
@@ -461,6 +465,8 @@ spec:
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]
@@ -490,6 +496,8 @@ START-x509-client-replset-lower-custom
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]
@@ -516,6 +524,8 @@ spec:
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]
@@ -546,6 +556,8 @@ START-x509-internal-replset-lower-custom
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]

source/includes/code-examples/yaml-files/example-sharded-cluster.yaml

@@ -249,27 +249,6 @@ spec:
 ...
 END-auth-scram-x509-sharded
 
-START-sharded
----
-apiVersion: mongodb.com/v1
-kind: MongoDB
-metadata:
-  name: <my-secure-sharded-cluster>
-spec:
-  shardCount: 2
-  mongodsPerShardCount: 3
-  mongosCount: 2
-  configServerCount: 3
-  version: "4.2.2-ent"
-  opsManager:
-    configMapRef:
-      name: <configMap.metadata.name>
-            # Must match metadata.name in ConfigMap file
-  credentials: <mycredentials>
-  type: ShardedCluster
-  persistent: true
-...
-END-minimal-sharded
 
 START-scaled-sharded
 ---
@@ -316,6 +295,8 @@ spec:
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
 ...
 END-tls-sharded-full-custom
 
@@ -345,6 +326,8 @@ START-tls-sharded-lower-custom
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
 ...
 END-tls-sharded-lower-custom
 
@@ -371,6 +354,8 @@ spec:
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]
@@ -403,6 +388,8 @@ START-x509-client-sharded-lower-custom
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]
@@ -432,6 +419,8 @@ spec:
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]
@@ -465,6 +454,8 @@ START-x509-internal-sharded-lower-custom
     tls:
       enabled: true
       ca: <custom-ca>
+      secretRef:
+        prefix: <prefix>
     authentication:
       enabled: true
       modes: ["X509"]

source/includes/list-tables/resource-keys-tls-custom-ca.rst

@@ -1,5 +1,5 @@
 .. list-table::
-   :widths: 20 10 10 40 20
+   :widths: 25 10 10 40 15
    :header-rows: 1
 
    * - Key
@@ -26,3 +26,13 @@
      - If you use a custom |certauth| and have created the 
        |k8s-configmap| that stores it, add the ConfigMap's name.
      - ``<custom-ca>``
+
+   * - | ``spec.security``
+       | :setting:`.tls.secretRef.prefix<spec.security.tls.secretRef.prefix>`
+     - string
+     - Optional
+     - Add the ``<prefix>`` of the |k8s| |k8s-secret| name that contains
+       your MongoDB deployment's |tls| certificates. If you omit this
+       setting, the prefix defaults to the value of
+       :setting:`metadata.name` of your MongoDB resource.
+     - ``<prefix>``

source/includes/options-k8s-replica-set.yaml

@@ -477,6 +477,20 @@ inherit:
   file: options-k8s-shared.yaml
 ---
 program: k8sRsConf
+name: spec.security.tls.secretRef.name
+inherit:
+  name: spec.security.tls.secretRef.name
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.tls.secretRef.prefix
+inherit:
+  name: spec.security.tls.secretRef.prefix
+  program: _shared
+  file: options-k8s-shared.yaml
+---
+program: k8sRsConf
 name: spec.security.authentication.modes
 inherit:
   name: spec.security.authentication.modes

source/includes/options-k8s-shared.yaml

@@ -572,6 +572,29 @@ description: |
   Provide the name of the |k8s-configmap| that stores the |certauth|.
 ---
 program: _shared
+name: spec.security.tls.secretRef.name
+type: string
+directive: setting
+optional: true
+description: |
+  Deprecated. Use :setting:`spec.security.tls.secretRef.prefix` instead.
+  Provide the name of the |k8s| |k8s-secret| you created that contains
+  your MongoDB deployment's |tls| certificates.
+---
+program: _shared
+name: spec.security.tls.secretRef.prefix
+type: string
+directive: setting
+optional: true
+description: |
+  Provide the ``<prefix>`` of the |k8s| |k8s-secret| name that you
+  created that contains your MongoDB deployment's |tls| certificates.
+  The full |k8s-secret| name has the following format:
+  ``<prefix>-cert``. If you omit this setting, the prefix
+  defaults to the value of :setting:`metadata.name` of your
+  |k8s-mdbrsc|.
+---
+program: _shared
 name: spec.security.authentication
 type: collection
 directive: setting

source/includes/prereqs/custom-ca-prereqs-naming-conventions.rst

@@ -11,5 +11,5 @@
 
      - Replace ``<X>`` with the member of a shard or replica set.
 
-   - End the |pem| files with ``-pem`` and *not* ``.pem``.
+   - End the files with ``-cert`` and *not* ``.cert``.
      These files shouldn't have a file extension.

source/includes/prereqs/custom-ca-prereqs-rs-tls-only.rst

@@ -9,12 +9,12 @@
      * - Your custom |certauth|
        - ``ca-pem``
      * - Each member of your replica set
-       - ``<metadata.name>-<X>-pem``
+       - ``<metadata.name>-<X>-cert``
 
   .. include:: /includes/prereqs/pem-file-description.rst
 
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst
 
-  .. admonition:: About the Domain Names in certificates
+  .. note:: About the Domain Names in certificates
 
      .. include:: /includes/prereqs/pem-file-domain-name.rst

source/includes/prereqs/custom-ca-prereqs-rs-tls-x509-internal.rst

@@ -9,7 +9,7 @@
      * - Your custom |certauth|
        - ``ca-pem``
      * - Each member of your replica set
-       - ``<metadata.name>-<X>-pem``
+       - ``<metadata.name>-<X>-cert``
      * - Your project's Automation or MongoDB Agent
        - ``mms-automation-agent-pem``
      * - Your project's Backup Agent (if needed)

source/includes/prereqs/custom-ca-prereqs-sc-tls-only.rst

@@ -9,10 +9,10 @@
      * - Your custom |certauth|
        - ``ca-pem``
      * - Each shard in your sharded cluster
-       - ``<metadata.name>-<Y>-<X>-pem``
+       - ``<metadata.name>-<Y>-<X>-cert``
      * - Each member of your config server replica set
-       - ``<metadata.name>-config-<X>-pem``
+       - ``<metadata.name>-config-<X>-cert``
      * - Each |mongos|
-       - ``<metadata.name>-mongos-<X>-pem``
+       - ``<metadata.name>-mongos-<X>-cert``
 
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst

source/includes/prereqs/custom-ca-prereqs-sc-tls-x509-internal.rst

@@ -9,11 +9,11 @@
      * - Your custom |certauth|
        - ``ca-pem``
      * - Each shard in your sharded cluster
-       - ``<metadata.name>-<Y>-<X>-pem``
+       - ``<metadata.name>-<Y>-<X>-cert``
      * - Each member of your config server replica set
-       - ``<metadata.name>-config-<X>-pem``
+       - ``<metadata.name>-config-<X>-cert``
      * - Each |mongos|
-       - ``<metadata.name>-mongos-<X>-pem``
+       - ``<metadata.name>-mongos-<X>-cert``
      * - Your project's Automation or MongoDB Agent
        - ``mms-automation-agent-pem``
      * - Your project's Backup Agent (if needed)

source/includes/prereqs/custom-ca-prereqs.rst

@@ -9,18 +9,18 @@
      * - Your custom |certauth|
        - ``ca-pem``
      * - Each member of your replica set
-       - ``<metadata.name>-<X>-pem``
+       - ``<metadata.name>-<X>-cert``
      * - Your project's Automation or MongoDB Agent
        - ``mms-automation-agent-pem``
      * - Your project's Backup Agent (if needed)
        - ``mms-backup-agent-pem``
      * - Your project's Monitoring Agent (if needed)
        - ``mms-monitoring-agent-pem``
      * - Each shard in your sharded cluster
-       - ``<metadata.name>-<Y>-<X>-pem``
+       - ``<metadata.name>-<Y>-<X>-cert``
      * - Each member of your config server replica set
-       - ``<metadata.name>-config-<X>-pem``
+       - ``<metadata.name>-config-<X>-cert``
      * - Each |mongos|
-       - ``<metadata.name>-mongos-<X>-pem``
+       - ``<metadata.name>-mongos-<X>-cert``
 
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst

source/includes/prereqs/secure-om-resource.rst

@@ -15,14 +15,14 @@
      * - DNS Names
        - Each certificate must include a |san-dns| or Subject Name
          with the name of the |k8s-pod| in |k8s|. These names must
-         resemble this format:
+         use this format:
 
          .. code-block:: sh
 
             <opsmgr-name>-db-<index>.<opsmgr-name>-db-svc.<namespace>.svc.cluster.local
 
      * - Key Usages
-       - MongoDB requires the |tls| certs to include two specific
+       - MongoDB requires the |tls| certificates to include two specific
          key-usages (:rfc:`5280 <5280#section-4.2.1.3>`):
 
          - "server auth"

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

@@ -509,16 +509,18 @@ content: |
         Create this database as a :ref:`replica set
         <deploy-replica-set>`.
 
+     .. include:: /includes/admonitions/deprecate-secret-ref-name.rst
+
      Match the ``metadata.name`` of the resource with the
-     :opsmgrkube:`spec.backup.opLogStores.mongodbResourceRef.name` that you specified
-     in your |onprem| resource definition.
+     :opsmgrkube:`spec.backup.opLogStores.mongodbResourceRef.name`
+     that you specified in your |onprem| resource definition.
 
   #. Choose one of the following:
 
      i. Deploy a :ref:`MongoDB database resource
         <k8s-deploy-mdb-resources>` for the blockstore in the
         same namespace as the |onprem| resource.
-
+        
         Match the ``metadata.name`` of the resource to the
         :opsmgrkube:`spec.backup.blockStores.mongodbResourceRef.name`
         that you specified in your |onprem| resource definition.