(DOCSP-5656): Kubernetes X.509 project and internal cluster auth. (#45)

Author: jdestefano-mongo

conf.py

@@ -86,6 +86,8 @@
     '.. |cifs| replace:: :abbr:`CIFS (Common Internet File System)`',
     '.. |com| replace:: Cloud Manager or Ops Manager',
     '.. |compass| replace:: :compass:`MongoDB Compass </>`',
+    '.. |csr| replace:: :abbr:`CSR (Certificate Signing Request)`',
+    '.. |csrs| replace:: :abbr:`CSRs (Certificate Signing Requests)`',
     '.. |dns| replace:: :abbr:`DNS (Domain Name System)`',
     '.. |dns-srv| replace:: :abbr:`DNS (Domain Name System)` :abbr:`SRV (Service)`',
     '.. |ent-build| replace:: MongoDB Enterprise',

source/configuration.txt

@@ -21,5 +21,5 @@ Configure the |k8s-op-short|
    .. toctree::
       :titlesonly:
 
-      /tutorial/create-project-using-configmap
       /tutorial/create-operator-credentials
+      /tutorial/create-project-using-configmap

source/includes/list-table-configmap-keys-x509.rst

@@ -0,0 +1,22 @@
+.. list-table::
+   :widths: 20 20 40 20
+   :header-rows: 1
+
+   * - Key
+     - Type
+     - Description
+     - Example
+
+   * - ``data.authenticationMode``
+     - string
+     - Requires all agents to use X.509 client authentication when
+       communicating with MongoDB deployments.
+     - ``x509``
+
+   * - ``data.credentials``
+     - string
+     - Name of the |k8s| secret containing the |com| username and Public
+       API key. If you have not created these credentials yet,
+       see :ref:`create-k8s-secret`.
+
+     - ``mycredentials``

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

@@ -299,4 +299,11 @@ inherit:
   name: spec.additionalMongodConfig.net.ssl.mode
   program: _shared
   file: options-k8s-shared.yaml
+---
+program: k8sRsConf
+name: spec.security.clusterAuthenticationMode
+inherit:
+  name: spec.security.clusterAuthenticationMode
+  program: _shared
+  file: options-k8s-shared.yaml
 ...

source/includes/options-k8s-shared.yaml

@@ -422,5 +422,21 @@ description: |
   The following are valid options:
 
   .. include:: /includes/list-table-requiressl-modes.rst
+---
+program: _shared
+name: spec.security.clusterAuthenticationMode
+type: string
+directive: setting
+optional: true
+description: |
+
+  Set to ``x509`` to enable
+  :ref:`X.509 internal cluster authentication <x509-internal-authentication>`.
+  Requires |tls| on the resource by setting
+  :setting:`spec.security.tls.enabled` to ``true``.
+
+  .. important::
 
+     Once internal cluster authentication is enabled, it can not be
+     disabled.
 ...

source/includes/steps-create-k8s-configmap-tls.yaml

@@ -88,15 +88,34 @@ source:
 ---
 stepnum: 7
 level: 4
+ref: configure-configmap-x509-tls
+source:
+  file: steps-create-k8s-configmap.yaml
+  ref: configure-configmap-x509
+replacement:
+  example: |
+    .. literalinclude:: /reference/k8s/example-configmap-tls-x509.yaml
+       :language: yaml
+       :emphasize-lines: 16-17
+---
+stepnum: 8
+level: 4
 ref: create-k8s-configmap-tls
 source:
   file: steps-create-k8s-configmap.yaml
   ref: create-k8s-configmap
 ---
-stepnum: 8
+stepnum: 9
 level: 4
 ref: verify-k8s-configmap-tls
 source:
   file: steps-create-k8s-configmap.yaml
   ref: verify-k8s-configmap
+---
+stepnum: 10
+level: 4
+ref: approve-agent-certificates-tls
+source:
+  file: steps-create-k8s-configmap.yaml
+  ref: approve-agent-certificates
 ...

source/includes/steps-create-k8s-configmap.yaml

@@ -21,13 +21,51 @@ ref: configure-k8s-configmap
 content: |
   .. include:: /includes/list-table-configmap-keys.rst
 ---
-title: "Save this file with a ``.yaml`` file extension."
+title: "(Optional) Enable X.509 authentication at the |com| project level."
 stepnum: 4
 level: 4
+ref: configure-configmap-x509
+content: |
+
+  Enabling X.509 authentication at the project level configures all agents
+  to use X.509 client authentication when communicating with MongoDB
+  deployments.
+
+  |cloud-short| or one of the following versions of |onprem| is required
+  to use X.509 client authentication:
+
+  .. list-table::
+     :widths: 50 50
+     :header-rows: 1
+
+     * - |onprem| Version
+       - Required Patch
+
+     * - |onprem| 4.1
+       - 4.1.7
+
+     * - |onprem| 4.0
+       - 4.0.11
+
+  To enable X.509 authentication, add the highlighted lines to your
+  ConfigMap:
+
+  {{example}}
+
+  .. include:: /includes/list-table-configmap-keys-x509.rst
+replacement:
+  example: |
+    .. literalinclude:: /reference/k8s/example-configmap-x509.yaml
+       :language: yaml
+       :emphasize-lines: 13-14
+---
+title: "Save this file with a ``.yaml`` file extension."
+stepnum: 5
+level: 4
 ref: save-k8s-configmap
 ---
 title: "Invoke the |k8s| command to create your |k8s-configmap|."
-stepnum: 5
+stepnum: 6
 level: 4
 ref: create-k8s-configmap
 content: |
@@ -42,7 +80,7 @@ content: |
      specified in your |k8s-configmap|.
 ---
 title: "Invoke the |k8s| command to verify your |k8s-configmap|."
-stepnum: 6
+stepnum: 7
 level: 4
 ref: verify-k8s-configmap
 content: |
@@ -67,4 +105,46 @@ content: |
      Namespace:      <metadata.namespace>
      Labels:         <none>
      Annotations:    <none>
+---
+title: "If X.509 is enabled, approve the X.509 client certificates for the agents."
+stepnum: 8
+level: 4
+ref: approve-agent-certificates
+content: |
+  .. note::
+
+     If X.509 client authentication was *not* enabled in step 4, skip
+     this step.
+
+  Run the following command to verify the agent certificate signing
+  requests are pending:
+
+  .. code-block:: sh
+
+     kubectl get csr
+
+  The command returns the following output:
+
+  .. code-block:: sh
+     :copyable: false
+
+     NAME                           AGE       REQUESTOR                                                   CONDITION
+     mms-automation-agent.mongodb   4s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+     mms-backup-agent.mongodb       0s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+     mms-monitoring-agent.mongodb   3s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+
+  Approve the certificate for each agent using the ``NAME`` field
+  above in the following command:
+
+  .. code-block:: sh
+
+     kubectl certificate approve <NAME>
+
+  The following commands approve the agent |csrs|:
+
+  .. code-block:: sh
+
+     kubectl certificate approve mms-automation-agent.mongodb
+     kubectl certificate approve mms-backup-agent.mongodb
+     kubectl certificate approve mms-monitoring-agent.mongodb
 ...

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

@@ -11,7 +11,7 @@ content: |
 
    .. literalinclude:: /reference/k8s/example-replica-set-tls.yaml
       :language: yaml
-      :emphasize-lines: 5-7,9-13,16-22
+      :emphasize-lines: 5-7,9-13,16-24
 ---
 stepnum: 2
 level: 4
@@ -55,6 +55,20 @@ content: |
          accept TLS encrypted connections.
        - ``true``
 
+     * - :setting:`spec.security.clusterAuthenticationMode`
+       - string
+       - *Optional.* Enables :ref:`X.509 internal cluster authentication <x509-internal-authentication>`.
+
+         Remove this field from your ConfigMap to disable X.509 internal
+         cluster authentication.
+
+         .. important::
+
+            Once internal cluster authentication is enabled, it can not be
+            disabled.
+
+       - ``x509``
+
      * - :setting:`spec.additionalMongodConfig.net.ssl.mode`
        - string
        - *Optional.* Changes the :setting:`TLS mode <net.ssl.mode>`
@@ -125,26 +139,136 @@ level: 4
 ref: approve-certificates-tls
 content: |
 
-  Approve the certificate for each host using the following command:
+  Retrieve the |csrs| for each host by running the following command:
 
   .. code-block:: sh
 
-     kubectl certificate approve <metadata.name>-<member>.<namespace>
+     kubectl get csr
+
+  The output of the command and number of certificates to approve
+  depend on whether X.509 internal cluster authentication is enabled by
+  setting :setting:`spec.security.clusterAuthenticationMode` to
+  ``x509`` in step 4.
+
+  .. tabs::
+
+     tabs:
+       - id: x509disabled
+         name: X.509 Disabled
+         content: |
+           The command's output resembles the following:
+
+           .. code-block:: sh
+
+              NAME                                 AGE       REQUESTOR                                                   CONDITION
+              my-secure-rs-0.mongodb               33s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-1.mongodb               31s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-2.mongodb               24s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+
+           Using the ``NAME`` field above, approve each certificate from the
+           previous command's output using the following command:
+
+           .. code-block:: sh
+
+              kubectl certificate approve <NAME>
+
+           .. example::
+
+              The following commands approve the certificates for the
+              replica set example in the previous step:
+
+              .. code-block:: sh
+                 :copyable: false
+
+                 kubectl certificate approve my-secure-rs-0.mongodb
+                 kubectl certificate approve my-secure-rs-1.mongodb
+                 kubectl certificate approve my-secure-rs-2.mongodb
+
+           |kubectl| prints a message to the console when a certificate
+           is approved.
+
+       - id: x509enabled
+         name: X.509 Enabled
+         content: |
+
+           The command's output resembles the following:
+
+           .. code-block:: sh
+
+              NAME                           AGE       REQUESTOR                                                   CONDITION
+              mms-automation-agent.mongodb   15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              mms-backup-agent.mongodb       15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              mms-monitoring-agent.mongodb   15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              my-secure-rs-0.mongodb         6s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-1.mongodb         4s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-2.mongodb         1s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+
+           Using the ``NAME`` field above, approve each certificate from the
+           previous command's output using the following command:
+
+           .. code-block:: sh
+
+              kubectl certificate approve <NAME>
+
+           .. example::
+
+              The following commands approve the certificates for the
+              replica set example in the previous step:
+
+              .. code-block:: sh
+                 :copyable: false
+
+                 kubectl certificate approve my-secure-rs-0.mongodb
+                 kubectl certificate approve my-secure-rs-1.mongodb
+                 kubectl certificate approve my-secure-rs-2.mongodb
+
+           |kubectl| prints a message to the console when a certificate
+           is approved.
+
+           When :setting:`spec.security.clusterAuthenticationMode` is set to
+           ``x509`` an additional |csr| will be generated per host for the
+           clusterfile.
+
+           After the first batch of certificates are approved, run the
+           command to retrieve the |csrs| again:
+
+           .. code-block:: sh
+
+              kubectl get csr
+
+           The clusterfile |csrs| are now present in the output:
+
+           .. code-block:: sh
+              :copyable: false
+
+              NAME                                       AGE       REQUESTOR                                                   CONDITION
+              mms-automation-agent.mongodb               17m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              mms-backup-agent.mongodb                   17m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              mms-monitoring-agent.mongodb               17m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              my-secure-rs-0-clusterfile.mongodb         13s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-0.mongodb                     105s      system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              my-secure-rs-1-clusterfile.mongodb         7s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-1.mongodb                     103s      system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+              my-secure-rs-2-clusterfile.mongodb         3s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
+              my-secure-rs-2.mongodb                     100s      system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued
+
+           Approve the clusterfile |csrs| using the same command:
+
+           .. code-block:: sh
 
-  .. example::
+              kubectl certificate approve <NAME>
 
-     The following commands approve the certificates for the
-     replica set example in the previous step:
+           .. example::
 
-     .. code-block:: sh
-        :copyable: false
+              The following commands approve the clusterfile
+              certificates:
 
-        kubectl certificate approve my-secure-rs-0.my-namespace
-        kubectl certificate approve my-secure-rs-1.my-namespace
-        kubectl certificate approve my-secure-rs-2.my-namespace
+              .. code-block:: sh
+                 :copyable: false
 
-  The |k8s-op-short| prints a message to the console when a certificate
-  is approved.
+                 kubectl certificate approve my-secure-rs-0-clusterfile.mongodb
+                 kubectl certificate approve my-secure-rs-1-clusterfile.mongodb
+                 kubectl certificate approve my-secure-rs-2-clusterfile.mongodb
 ---
 title: "Track the status of your deployment."
 level: 4