(DOCSP-17997)(DOCSP-17751)(DOCSP-18205): fix x509 procedures (#720)

* (DOCSP-17997)(DOCSP-17751)(DOCSP-18205): fix x509 procedures

* (DOCSP-17997)(DOCSP-17751)(DOCSP-18205): renew agent certs

* Apply suggestions from code review

Co-authored-by: Melissa Mahoney <[email protected]>

* (DOCSP-17997)(DOCSP-17751)(DOCSP-18205): add k8s versions in client certs prereqs page

* Update resource-keys-client-x509.rst

* (DOCSP-17997): settings clean up

Co-authored-by: Melissa Mahoney <[email protected]>

Author: jwilliams-mongo

source/includes/list-tables/resource-keys-client-x509.rst

@@ -12,8 +12,8 @@
        | ``.authentication``
        | :setting:`.enabled<spec.security.authentication.enabled>`
      - boolean
-     - Optional
-     - If this value is ``true``, authentication is enabled on the
+     - Required
+     - Set this value to ``true`` to enable authentication on the
        MongoDB deployment.
 
      - ``true``
@@ -23,7 +23,5 @@
        | :setting:`.modes<spec.security.authentication.modes>`
      - array
      - Conditional
-     - If you enabled authentication, you must set an authentication
-       mechanism. Accepted values are ``X509``.
-     - ``X509``
-
+     - Set this value to ``["X509"]``.
+     - ``["X509"]``

source/includes/list-tables/resource-keys-internal-x509.rst

@@ -12,16 +12,13 @@
        | ``.authentication``
        | :setting:`.internalCluster<spec.security.authentication.internalCluster>`
      - string
-     - Conditional
-     - If you enabled authentication, you can enable
+     - Required
+     - Use this setting to enable
        :manual:`X.509 internal cluster authentication </tutorial/configure-x509-member-authentication#x509-internal-authentication>`.
-       Accepted values are ``X509``.
 
        .. important::
 
-          Once internal cluster authentication is enabled, it can not
+          Once internal cluster authentication is enabled, it can't
           be disabled.
 
      - ``X509``
-
-

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

@@ -11,7 +11,7 @@
    * - | ``spec.security``
        | :setting:`.tls.enabled<spec.security.tls.enabled>`
      - boolean
-     - Optional
+     - Required
      - If this value is ``true``, |tls| is enabled on the MongoDB
        deployment.
 
@@ -22,9 +22,9 @@
    * - | ``spec.security``
        | :setting:`.tls.ca<spec.security.tls.ca>`
      - string
-     - Optional
-     - If you use a custom |certauth| and have created the 
-       |k8s-configmap| that stores it, add the ConfigMap's name.
+     - Required
+     - Add the |k8s-configmap|\'s name that stores the custom |certauth|
+       that you used to sign your deployment's |tls| certificates.
      - ``<custom-ca>``
 
    * - | ``spec.security``

source/includes/options-k8s-shared.yaml

@@ -658,11 +658,8 @@ default: "``false``"
 description: |
 
   Specifies whether the MongoDB host requires clients to connect using a
-  |tls| certificate. If ``true``, you must:
-
-  - Specify a certificate for the {+mdbagent+} in
-    :setting:`spec.security.authentication.agents.clientCertificateSecretRef.name`.
-  - Set :setting:`spec.security.tls.enabled` to ``true``.
+  |tls| certificate. Defaults to ``true`` if
+  :setting:`spec.security.tls.enabled` is ``true``.
 
 ---
 program: _shared
@@ -1132,7 +1129,7 @@ optional: true
 description: |
 
   Specifies the |k8s-secret| that contains the {+mdbagent+}'s
-  |tls| certificate.
+  |tls| certificate. If omitted, defaults to ``agent-certs``.
 
   This secret must contain the following keys, the 
   values of which are |tls| certificates that can be validated by the 
@@ -1153,9 +1150,6 @@ description: |
      --from-file=mms-monitoring-agent-pem=<monitoring-cert.pem> \
      -n <namespace>
 
-  This setting is required if 
-  :setting:`spec.security.authentication.requireClientTLSAuthentication` is ``true``.
-
 ---
 program: _shared
 name: spec.additionalMongodConfig.net.ssl.mode

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

@@ -1,4 +1,4 @@
-.. admonition:: About the example filenames
+.. note:: About the example filenames
 
    - Name these files the exact names provided, substituting the
      appropriate variables. If a filename doesn't match, deployment

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

@@ -10,11 +10,25 @@
        - ``ca-pem``
      * - Each member of your replica set
        - ``<metadata.name>-<X>-pem``
+     * - 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``
+
+  For the Agent PEM files, ensure that:
+
+  - the Common Name in each |tls| certificate is not empty, and
+  - the combined Organization and Organizational Unit in each |tls|
+    certificate differs from the combined Organization and
+    Organizational Unit in the |tls| certificates for your
+    replica set members.
 
   .. include:: /includes/prereqs/pem-file-description.rst
 
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst
 
   .. note:: About the Domain Names in certificates
 
-     .. include:: /includes/prereqs/pem-file-domain-name.rst
+     .. include:: /includes/prereqs/pem-file-domain-name.rst

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

@@ -17,4 +17,18 @@
      * - Your project's Monitoring Agent (if needed)
        - ``mms-monitoring-agent-pem``
 
+  For the Agent PEM files, ensure that:
+
+  - the Common Name in each |tls| certificate is not empty, and
+  - the combined Organization and Organizational Unit in each |tls|
+    certificate differs from the combined Organization and
+    Organizational Unit in the |tls| certificates for your
+    replica set members.
+
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst
+
+  .. include:: /includes/prereqs/pem-file-description.rst
+
+  .. note:: About the Domain Names in certificates
+  
+     .. include:: /includes/prereqs/pem-file-domain-name.rst

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

@@ -14,5 +14,25 @@
        - ``<metadata.name>-config-<X>-pem``
      * - Each |mongos|
        - ``<metadata.name>-mongos-<X>-pem``
+     * - 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``
+
+  For the Agent PEM files, ensure that:
+
+  - the Common Name in each |tls| certificate is not empty, and
+  - the combined Organization and Organizational Unit in each |tls|
+    certificate differs from the combined Organization and
+    Organizational Unit in the |tls| certificates for your
+    sharded cluster members, config server members, and each |mongos|.
+
+  .. include:: /includes/prereqs/pem-file-description.rst
 
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst
+
+  .. note:: About the Domain Names in certificates
+  
+     .. include:: /includes/prereqs/pem-file-domain-name.rst

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

@@ -21,4 +21,18 @@
      * - Your project's Monitoring Agent (if needed)
        - ``mms-monitoring-agent-pem``
 
+  For the Agent PEM files, ensure that:
+
+  - the Common Name in each |tls| certificate is not empty, and
+  - the combined Organization and Organizational Unit in each |tls|
+    certificate differs from the combined Organization and
+    Organizational Unit in the |tls| certificates for your
+    sharded cluster members, config server members, and each |mongos|.
+
+  .. include:: /includes/prereqs/pem-file-description.rst
+
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst
+
+  .. note:: About the Domain Names in certificates
+  
+     .. include:: /includes/prereqs/pem-file-domain-name.rst

source/includes/steps-connect-to-x509-deployment.yaml

@@ -22,13 +22,13 @@ content: |
      metadata:
        name: new-x509-user
      spec:
-       username: "CN=my-x509-authenticated-user, OU=organizationalunit, O=organization"
+       username: "CN=my-x509-authenticated-user,OU=organizationalunit,O=organization"
        db: "$external"
        mongodbResourceRef:
          name: '<name of the MongoDB resource>'
        roles:
          - db: "admin"
-           name: "clusterAdmin"
+           name: "readWriteAnyDatabase"
 
   This ConfigMap ``.yaml`` file describes a ``MongoDBUser`` custom object. You
   can use these custom objects to create MongoDB users.
@@ -81,23 +81,23 @@ stepnum: 5
 ref: connect-with-x509-user
 content: |
   Once you have created your X.509 user, try to connect to the
-  deployment using the mongo Shell:
+  deployment using the MongoDB Shell (``mongosh``):
 
   .. tabs::
 
-     .. tab:: MongoDB 4.2
+     .. tab:: MongoDB 4.2 and later
         :tabid: mdb-4-2
 
         .. code-block:: sh
 
-           mongo --host {host} --tls --tlsCAFile /var/run/secrets/kubernetes.io/serviceaccount/ca.crt --tlsCertificateKeyFile x509-full.pem --authenticationMechanism MONGODB-X509 --authenticationDatabase '$external'
+           mongosh --host {host} --port {port} --tls --tlsCAFile /var/run/secrets/kubernetes.io/serviceaccount/ca.crt --tlsCertificateKeyFile x509-full.pem --authenticationMechanism MONGODB-X509 --authenticationDatabase '$external'
 
-     .. tab:: MongoDB 4.0 and Older
+     .. tab:: MongoDB 4.0 and earlier
         :tabid: mdb-4-0-and-older
 
         .. code-block:: sh
 
-           mongo --host {host} --ssl --sslCAFile /var/run/secrets/kubernetes.io/serviceaccount/ca.crt --sslPEMKeyFile x509-full.pem --authenticationMechanism MONGODB-X509 --authenticationDatabase '$external'
+           mongosh --host {host} --port {port} --ssl --sslCAFile /var/run/secrets/kubernetes.io/serviceaccount/ca.crt --sslPEMKeyFile x509-full.pem --authenticationMechanism MONGODB-X509 --authenticationDatabase '$external'
 
   .. note::
 

source/includes/steps-deploy-k8s-replica-set-tls-custom.yaml

@@ -12,13 +12,19 @@ source:
   ref: create-rs-tls-secret
 ---
 stepnum: 3
+ref: create-k8s-rs-agent-secret
+source:
+  file: steps-source-deploy-k8s-resource.yaml
+  ref: create-agent-tls-secret
+---
+stepnum: 4
 ref: create-k8s-rs-tls-configmap
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: create-rs-tls-configmap
 
 ---
-stepnum: 4
+stepnum: 5
 ref: copy-k8s-example-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -45,31 +51,31 @@ replacement:
       :emphasize-lines: 1-7
 
 ---
-stepnum: 5
+stepnum: 6
 ref: paste-k8s-example-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: paste-k8s-example-resource-section
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 6
+stepnum: 7
 ref: k8s-add-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: add-tls-settings-custom-ca
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 7
+stepnum: 8
 ref: save-object-spec-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: save-object-spec-update
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 8
+stepnum: 9
 ref: start-k8s-deployment-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -78,7 +84,7 @@ replacement:
   k8sResource: :term:`replica set`
   k8sResourceType: replica-set
 ---
-stepnum: 9
+stepnum: 10
 title: "Track the status of your deployment."
 level: 4
 ref: track-k8s-deployment-basic-rs-tls

source/includes/steps-deploy-k8s-replica-set-x509-custom.yaml

@@ -12,12 +12,18 @@ source:
   ref: create-rs-tls-secret
 ---
 stepnum: 3
+ref: create-k8s-rs-agent-secret
+source:
+  file: steps-source-deploy-k8s-resource.yaml
+  ref: create-agent-tls-secret
+---
+stepnum: 4
 ref: create-k8s-rs-tls-configmap
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: create-rs-tls-configmap
 ---
-stepnum: 4
+stepnum: 5
 ref: copy-k8s-example-rs-x509
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -44,39 +50,39 @@ replacement:
       :emphasize-lines: 1-10
 
 ---
-stepnum: 5
+stepnum: 6
 ref: paste-k8s-example-rs-x509
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: paste-k8s-example-resource-section
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 6
+stepnum: 7
 ref: k8s-add-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: add-tls-settings-custom-ca
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 7
+stepnum: 8
 ref: k8s-add-rs-x509
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: add-client-x509-settings
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 8
+stepnum: 9
 ref: save-object-spec-rs-x509
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: save-object-spec-update
 replacement:
   k8sResource: :term:`replica set`
 ---
-stepnum: 9
+stepnum: 10
 ref: start-k8s-deployment-rs-x509
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -86,7 +92,7 @@ replacement:
   k8sResourceType: replica-set
 ---
 title: "Track the status of your deployment."
-stepnum: 10
+stepnum: 11
 level: 4
 ref: track-k8s-deployment-rs-x509
 content: |