DOCSP-21687: TLS instruction improvements (#904)

Author: jwilliams-mongo

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

@@ -12,11 +12,10 @@ spec:
     mms.fromEmailAddr: [email protected]
     mms.security.allowCORS: "false"
   security:
-    certsSecretPrefix:  <prefix> # Optional. Text to prefix to the name of the
+    certsSecretPrefix:  <prefix> # Required. Text to prefix to the name of the
                                  # secret that contains Ops Manager's TLS 
-                                 # certificate. If you omit
-                                 # this setting, name the secret 
-                                 # <metadata.name>-cert.    
+                                 # certificate. Name the secret 
+                                 # <prefix>-<metadata.name>-cert.    
     tls:
       ca: "opsmgr-ca" # Optional. Name of the ConfigMap file
                       # containing the certicate authority that
@@ -27,11 +26,10 @@ spec:
     members: 3
     version: "4.4.0-ent"
     security:
-      certsSecretPrefix: <prefix> # Optional. Text to prefix to the 
+      certsSecretPrefix: <prefix> # Required. Text to prefix to the 
                                   # name of the secret that contains the Application
-                                  # Database's TLS certificate. If you omit
-                                  # this setting, name the secret 
-                                  # <metadata.name>-db-cert.
+                                  # Database's TLS certificate. Name the secret 
+                                  # <prefix>-<metadata.name>-db-cert.
       tls:
         ca: "appdb-ca" # Optional. Name of the ConfigMap file
                        # containing the certicate authority that

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

@@ -1,15 +1,25 @@
 - Generate one |tls| certificate for each of the following components:
 
   - Each shard in your sharded cluster. Ensure that you add |san-dns|\s for 
-    each |k8s| pod that hosts a shard member to the certificate. 
+    each |k8s| pod that hosts a shard member to the certificate.
+
+    In your |tls| certificates, the |san-dns|
+    for each shard pod must use the following format:
+
+    .. include:: /includes/prereqs/san-format-shards.rst
 
   - Your config servers. Ensure that you add |san-dns|\s for 
     each |k8s| pod that hosts your config servers to the certificate. 
+    
+    In your |tls| certificates, the |san-dns|
+    for each config server pod must use the following format:
+
+    .. include:: /includes/prereqs/san-format-csrs.rst
 
   - Your |mongos| instances. Ensure that you add |san-dns|\s for 
     each |k8s| pod that hosts a |mongos| to the certificate. 
 
-    In your |tls| certificates, the |san-dns| for each pod must use this 
+    In your |tls| certificates, the |san-dns| for each |mongos| pod must use this 
     format:
 
     .. include:: /includes/prereqs/san-format.rst

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

@@ -4,15 +4,25 @@
 - Generate one |tls| certificate for each of the following components:
 
   - Each shard in your sharded cluster. Ensure that you add |san-dns|\s for 
-    each |k8s| pod that hosts a shard member to the certificate. 
+    each |k8s| pod that hosts a shard member to the certificate.
+
+    In your |tls| certificates, the |san-dns|
+    for each shard pod must use the following format:
+
+    .. include:: /includes/prereqs/san-format-shards.rst
 
   - Your config servers. Ensure that you add |san-dns|\s for 
     each |k8s| pod that hosts your config servers to the certificate. 
+    
+    In your |tls| certificates, the |san-dns|
+    for each config server pod must use the following format:
+
+    .. include:: /includes/prereqs/san-format-csrs.rst
 
   - Your |mongos| instances. Ensure that you add |san-dns|\s for 
     each |k8s| pod that hosts a |mongos| to the certificate. 
 
-    In your |tls| certificates, the |san-dns| for each pod must use this 
+    In your |tls| certificates, the |san-dns| for each |mongos| pod must use this 
     format:
 
     .. include:: /includes/prereqs/san-format.rst
@@ -22,18 +32,28 @@
 - Generate one X.509 certificate for each of the following components:
 
   - Each shard in your sharded cluster. Ensure that you add |san-dns|\s for 
-    each |k8s| pod that hosts a shard member to the certificate. 
+    each |k8s| pod that hosts a shard member to the certificate.
+
+    In your |tls| certificates, the |san-dns|
+    for each shard pod must use the following format:
+
+    .. include:: /includes/prereqs/san-format-shards.rst
 
   - Your config servers. Ensure that you add |san-dns|\s for 
     each |k8s| pod that hosts your config servers to the certificate. 
+    
+    In your |tls| certificates, the |san-dns|
+    for each config server pod must use the following format:
+
+    .. include:: /includes/prereqs/san-format-csrs.rst
 
   - Your |mongos| instances. Ensure that you add |san-dns|\s for 
     each |k8s| pod that hosts a |mongos| to the certificate. 
 
-  In your X.509 certificates, the |san-dns| for each pod must use this 
-  format:
+    In your |tls| certificates, the |san-dns| for each |mongos| pod must use this 
+    format:
 
-  .. include:: /includes/prereqs/san-format.rst
+    .. include:: /includes/prereqs/san-format.rst
 
 - You must possess the |certauth| certificate and the key that you used to 
   sign your |tls| certificates.

source/includes/prereqs/san-format-csrs.rst

@@ -0,0 +1,4 @@
+.. code-block:: none
+
+   <pod-name>.<metadata.name>-cs.<namespace>.svc.cluster.local
+

source/includes/prereqs/san-format-shards.rst

@@ -0,0 +1,4 @@
+.. code-block:: none
+
+   <pod-name>.<metadata.name>-sh.<namespace>.svc.cluster.local
+

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

@@ -15,7 +15,7 @@ content: |
 
    .. code-block:: sh
 
-      kubectl create secret tls <metadata.name>-cert \
+      kubectl create secret tls <prefix>-<metadata.name>-cert \
        --cert=<om-tls-cert> \
        --key=<om-tls-key>
 
@@ -61,8 +61,7 @@ content: |
 
      .. code-block:: sh
 
-        cat cert1.crt cert2.crt cert3.crt cert4.crt  >> ca-pem
-
+        cat cert1.crt cert2.crt cert3.crt cert4.crt  >> mms-ca.crt
   #. Create the |k8s-configmap|:
 
      .. code-block:: sh
@@ -152,13 +151,10 @@ content: |
           | ``.security``
           | ``.``:opsmgrkube:`~spec.security.certsSecretPrefix`
         - string
-        - *Optional*.
+        - *Required*.
         
           Text to prefix to the name of the secret that contains
           |onprem|\s |tls| certificates.
-
-          If you omit this setting, you must name the secret 
-          ``<metadata.name>-cert``.
         - ``om-prod``
 
       * - | ``spec``

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

@@ -358,7 +358,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl create secret tls <metadata.name>-cert \
+     kubectl create secret tls <prefix>-<metadata.name>-cert \
        --cert=<replica-set-tls-cert> \
        --key=<replica-set-tls-key>
 
@@ -384,7 +384,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl create secret tls <metadata.name>-agent-certs \
+     kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
        --cert=<agent-tls-cert> \
        --key=<agent-tls-key>
 
@@ -402,7 +402,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl create secret tls <metadata.name>-agent-certs \
+     kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
        --cert=<agent-tls-cert> \
        --key=<agent-tls-key> \
        --dry-run=client \
@@ -422,7 +422,7 @@ content: |
   .. code-block:: sh
 
 
-     kubectl create secret tls <metadata.name>-cert \
+     kubectl create secret tls <prefix>-<metadata.name>-cert \
        --cert=<replica-set-tls-cert> \
        --key=<replica-set-tls-key> \
        --dry-run=client \
@@ -445,7 +445,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl create secret tls <metadata.name>-clusterfile \
+     kubectl create secret tls <prefix>-<metadata.name>-clusterfile \
        --cert=<replica-set-clusterfile-tls-cert> \
        --key=<replica-set-clusterfile-tls-key>
 
@@ -467,7 +467,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl create secret tls <metadata.name>-clusterfile \
+     kubectl create secret tls <prefix>-<metadata.name>-clusterfile \
        --cert=<replica-set-clusterfile-tls-cert> \
        --key=<replica-set-clusterfile-tls-key> \
        --dry-run=client \
@@ -500,11 +500,11 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-0-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-cert \
        --cert=<shard-0-tls-cert> \
        --key=<shard-0-tls-key>
 
-     kubectl -n mongodb create secret tls <metadata.name>-1-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-cert \
        --cert=<shard-1-tls-cert> \
        --key=<shard-1-tls-key>
 
@@ -521,14 +521,14 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-0-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-cert \
        --cert=<shard-0-tls-cert> \
        --key=<shard-0-tls-key> \
        --dry-run=client \
        -o yaml |
      kubectl apply -f -
 
-     kubectl -n mongodb create secret tls <metadata.name>-1-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-cert \
        --cert=<shard-1-tls-cert> \
        --key=<shard-1-tls-key> \
        --dry-run=client \
@@ -547,7 +547,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-config-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-cert \
        --cert=<config-tls-cert> \
        --key=<config-tls-key>
 
@@ -565,7 +565,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-config-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-cert \
        --cert=<config-tls-cert> \
        --key=<config-tls-key> \
        --dry-run=client \
@@ -584,7 +584,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-mongos-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-cert \
        --cert=<mongos-tls-cert> \
        --key=<mongos-tls-key>
 
@@ -602,7 +602,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-mongos-cert \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-cert \
        --cert=<mongos-tls-cert> \
        --key=<mongos-tls-key> \
        --dry-run=client \
@@ -621,11 +621,11 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-0-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-clusterfile \
        --cert=<shard-0-clusterfile-tls-cert> \
        --key=<shard-0-clusterfile-tls-cert>
 
-     kubectl -n mongodb create secret tls <metadata.name>-1-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-clusterfile \
        --cert=<shard-1-clusterfile-tls-cert> \
        --key=<shard-1-clusterfile-tls-cert>
 
@@ -641,14 +641,14 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-0-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-clusterfile \
        --cert=<shard-0-clusterfile-tls-cert> \
        --key=<shard-0-clusterfile-tls-cert> \
        --dry-run=client \
        -o yaml |
      kubectl apply -f -
 
-     kubectl -n mongodb create secret tls <metadata.name>-1-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-clusterfile \
        --cert=<shard-1-clusterfile-tls-cert> \
        --key=<shard-1-clusterfile-tls-cert> \
        --dry-run=client \
@@ -667,7 +667,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-config-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-clusterfile \
        --cert=<config-clusterfile-tls-cert> \
        --key=<config-clusterfile-tls-cert>
 
@@ -683,7 +683,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-config-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-clusterfile \
        --cert=<config-clusterfile-tls-cert> \
        --key=<config-clusterfile-tls-cert> \
        --dry-run=client \
@@ -702,7 +702,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-mongos-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-clusterfile \
        --cert=<mongos-clusterfile-tls-cert> \
        --key=<mongos-clusterfile-tls-cert>
 
@@ -718,7 +718,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl -n mongodb create secret tls <metadata.name>-mongos-clusterfile \
+     kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-clusterfile \
        --cert=<mongos-clusterfile-tls-cert> \
        --key=<mongos-clusterfile-tls-cert> \
        --dry-run=client \

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

@@ -10,7 +10,7 @@ content: |
 
   .. code-block:: sh
 
-     kubectl create secret tls <metadata.name>-db-cert \
+     kubectl create secret tls <prefix>-<metadata.name>-db-cert \
        --cert=<appdb-tls-cert> \
        --key=<appdb-tls-key>
 
@@ -85,7 +85,7 @@ content: |
      :copyable: false
      :start-after: START-secure-appdb-full
      :end-before: END-secure-appdb-full
-     :emphasize-lines: 29-39
+     :emphasize-lines: 29-37
 
   .. note::
 

source/reference/k8s/example-opsmgr-https.yaml

@@ -13,7 +13,7 @@ spec:
   externalConnectivity:
     type: LoadBalancer
   security:
-      certsSecretPrefix: <prefix> # Optional. Text to prefix 
+      certsSecretPrefix: <prefix> # Required. Text to prefix 
                                   # the name of the secret that contains
                                   # Ops Manager's TLS certificate.
       tls:

source/tutorial/mdb-resources-arch.txt

@@ -225,14 +225,15 @@ performs the following actions to reconcile the changes:
 
    - If :ref:`TLS <secure-tls>` is enabled for a replica set, the
      |k8s-op-short| looks for certificates provided in the
-     ``<resource-name>-cert`` secret or your :ref:`secret storage tool <k8s-set-secret-storage-tool>`.
+     ``<prefix>-<resource-name>-cert`` secret or your 
+     :ref:`secret storage tool <k8s-set-secret-storage-tool>`.
 
    - If :ref:`TLS <secure-tls>` is enabled for a sharded cluster, the
      |k8s-op-short| looks for certificates in these secrets:
 
-     - ``<resource-name>-x-cert`` for each shard member.
-     - ``<resource-name>-config-cert`` for all config servers.
-     - ``<resource-name>-mongos-cert`` for all |mongos| instances.
+     - ``<prefix>-<resource-name>-x-cert`` for each shard member.
+     - ``<prefix>-<resource-name>-config-cert`` for all config servers.
+     - ``<prefix>-<resource-name>-mongos-cert`` for all |mongos| instances.
      - Your :ref:`secret storage tool <k8s-set-secret-storage-tool>`.
 
    - If :ref:`X.509 <create-x509-certs>` or