(DOCSP-13671) Prod notes troubleshooting, invalid DNS in TLS certs (#547)

* (DOCSP-13671) Prod notes troubleshooting, invalid DNS in TLS certs

* Renamed one file, added info, per Raj

* Include copy review from NL

Author: JuliaMongo

conf.py

@@ -59,7 +59,7 @@
 source_constants = {
     'version': version,
     'k8s-op-short': 'Kubernetes Operator',
-    'k8s-api-version': 'v1.20',
+    'k8s-api-version': 'v1.21',
     'aagent': 'MongoDB Agent or legacy Automation Agent',
     'aagents': 'MongoDB Agents or legacy Automation Agents',
     'mdbagent': 'MongoDB Agent',

source/includes/check-resource-status.rst

@@ -6,7 +6,7 @@ command:
    kubectl get mdb <resource-name> -o yaml -w
 
 The ``-w`` flag means "watch". With the "watch" flag set, the output
-refreshes immediately when something changes until the status phase
+refreshes immediately when the configuration changes until the status phase
 achieves the ``Running`` state.
 
 See :doc:`/reference/troubleshooting` for information about the resource

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

@@ -14,3 +14,7 @@
   .. include:: /includes/prereqs/pem-file-description.rst
 
   .. include:: /includes/prereqs/custom-ca-prereqs-naming-conventions.rst
+  
+  .. admonition:: About the Domain Names in certificates
+  
+     .. include:: /includes/prereqs/pem-file-domain-name.rst

source/includes/prereqs/pem-file-description.rst

@@ -2,6 +2,7 @@ To create the |pem| file, concatenate the |tls| certificate and the
 Private Key. An example of a |pem| file would resemble:
 
 .. code-block:: text
+   :copyable: false
 
    -----BEGIN CERTIFICATE-----
    ...

source/includes/prereqs/pem-file-domain-name.rst

@@ -0,0 +1,20 @@
+Each certificate should include a valid Domain Name.
+
+For each replica set or sharded cluster member, the Common Name, also
+known as the Domain Name, for that member's certificate must match
+the |fqdn| of the POD on which this cluster member
+is deployed.
+
+The |fqdn| name in each certificate has the following syntax:
+``pod-name.service-name.namespace.svc.cluster.local``. This name is
+different for each Pod hosting a member of the replica set or a
+sharded cluster.
+
+For example, for a member of a replica set deployed on a Pod with
+the name ``rs-mongos-0-0``, in the |k8s-op-short| service
+named ``mongo-0`` that is created in the default ``mongodb``
+namespace, the |fqdn| is:
+
+.. code-block:: sh
+
+   rs-mongos-0-0.mongo-0.mongodb.svc.cluster.local

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

@@ -281,7 +281,7 @@ level: 4
 ref: apply-changes-k8s-deployment
 content: |
 
-   Invoke the following |k8s| command to updated your
+   Invoke the following |k8s| command to update your
    {{k8sResource}}:
 
    .. code-block:: sh

source/index.txt

@@ -57,5 +57,6 @@ optimal performance.
       /specification
       Release Notes </release-notes>
       Production Notes </reference/production-notes>
+      /reference/troubleshooting
       Known Issues </reference/known-issues>
       MongoDB Community Kubernetes Operator <https://github.com/mongodb/mongodb-kubernetes-operator>

source/reference.txt

@@ -24,9 +24,6 @@ Reference
 :ref:`k8s-exclusive-settings`
   Review settings that only the |k8s-op-short| can set.
 
-:ref:`k8s-troubleshooting`
-  Find solutions to |k8s| issues.
-
 :ref:`k8s-support-lifecycle`
   Review the EOL dates for |k8s-op-short| versions.
 
@@ -42,7 +39,6 @@ Reference
       /reference/k8s-operator-specification
       /reference/operator-settings
       /reference/k8s-op-exclusive-settings
-      /reference/troubleshooting
       /reference/support-lifecycle
       /third-party-licenses
 

source/reference/production-notes.txt

@@ -529,7 +529,7 @@ Certificate Authority. To learn more, see
 </tasks/tls/managing-tls-in-a-cluster/>`.
 
 The default |tls| mode is ``requireTLS``. You can customize it using the
-the :setting:`spec.additionalMongodConfig.net.ssl.mode` configuration
+:setting:`spec.additionalMongodConfig.net.ssl.mode` configuration
 parameter, as shown in the following abbreviated example.
 
 .. code-block:: yaml

source/reference/troubleshooting.txt

@@ -35,7 +35,7 @@ invoke one of the following commands:
 
   .. note::
 
-     The ``opsManager`` controller watches the database resources
+     The |com| controller watches the database resources
      defined in the following settings:
 
      - :opsmgrkube:`spec.backup.opLogStores`
@@ -581,8 +581,8 @@ policy through the :opsmgr:`API </reference/api/controlled-features/update-contr
 
 .. _k8s-debug-failed container:
 
-Debugging a Failing Container
------------------------------
+Debug a Failing Container
+-------------------------
 
 A container might fail with an error that results in |k8s| restarting
 that container in a loop.
@@ -622,3 +622,39 @@ commands. This requires you to prevent the container from restarting.
 
       kubectl exec -it <pod-name> bash
 
+Verify Corrrectness of Domain Names in TLS Certificates
+-------------------------------------------------------
+
+A MongoDB replica set or sharded cluster may fail to reach
+the ``READY`` state if the |tls| certificate is invalid.
+
+When you :ref:`configure TLS
+<secure-tls>` for MongoDB replica sets or sharded clusters, verify
+that you specify a valid certificate.
+
+If you don't specify the correct Domain Name for each |tls| certificate,
+the |k8s-op-short| logs may contain an error message similar to the
+following, where ``foo.svc.local`` is the incorrectly-specified Domain
+Name for the cluster member's Pod:
+
+.. code-block:: sh
+   :copyable: false
+
+   TLS attempt failed : x509: certificate is valid for foo.svc.local,
+   not mongo-0-0.mongo-0.mongodb.svc.cluster.local
+
+.. include:: /includes/prereqs/pem-file-domain-name.rst
+
+To check whether you have correctly configured |tls| certificates:
+
+1. Run:
+
+   .. code-block:: sh
+
+      kubectl logs -f <pod_name>
+
+2. Check for |tls|-related messages in the |k8s-op-short| log files.
+
+To learn more about |tls| certificate requirements, see
+:ref:`TLS prerequisites <secure-tls-prerequisites>`.
+