(DOCSP-9612): Split Horizons tutorial needs to be fixed (#222)

* (DOCSP-9612): Split Horizons tutorial needs to be fixed

* (DOCSP-9612): tech review feedback

* (DOCSP-9612): more tech review updates

* (DOCSP-9612): more tech review

* (DOCSP-9612): fix steps

* (DOCSP-9612): last tech review feedback

Author: jwilliams-mongo

source/includes/code-examples/responses/k8s-cert-output.sh

@@ -124,6 +124,13 @@ my-secure-rs-1.mongodb                      31s       system:serviceaccount:mong
 my-secure-rs-2.mongodb                      24s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
 END-output-k8s-rs-tls-csrs
 
+START-output-k8s-rs-tls-csrs-approved
+NAME                                        AGE       REQUESTOR                                                   CONDITION
+my-secure-rs-0.mongodb                      33s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved, Issued
+my-secure-rs-1.mongodb                      31s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved, Issued
+my-secure-rs-2.mongodb                      24s       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved, Issued
+END-output-k8s-rs-tls-csrs-approved
+
 START-output-k8s-rs-x509-csrs
 NAME                                        AGE       REQUESTOR                                                   CONDITION
 mms-automation-agent.mongodb                15m       system:serviceaccount:mongodb:mongodb-enterprise-operator   Approved,Issued

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

@@ -368,6 +368,18 @@ START-horizon-addcert-replset-lower
 ...
 END-horizon-addcert-replset-lower
 
+START-horizon-addcert-replset-random-ports
+  security:
+    tls:
+      enabled: true
+  connectivity:
+    replicaSetHorizons:
+      - "example-website": "web1.example.com:10017"
+      - "example-website": "web2.example.com:10017"
+      - "example-website": "web3.example.com:10017"
+...
+END-horizon-addcert-replset-random-ports
+
 START-horizon-addcert-replset-lower-nodeports
   security:
     tls:

source/includes/steps-enable-split-horizon.yaml

@@ -1,6 +1,50 @@
+---
+title: If you haven't done so already, deploy a replica with the |k8s-op-short|.
+stepnum: 1
+level: 4
+ref: pre-deploy-replicaset
+content: |
+
+  Follow the instructions to :ref:` deploy a replica set 
+  <deploy-replica-set>`. To simplify the configuration, don't enable 
+  |tls| with the :setting:`spec.security.tls.enabled` setting.
+
+---
+title: "If you already deployed a replica set with the |k8s-op-short| with |tls| enabled, remove the |csrs| for each host in your deployment."
+level: 4
+ref: remove-tls-existing-replicasets
+stepnum: 2
+optional: true
+content: |
+  a. Invoke the following command to retrieve the |csrs| for each host:
+
+     .. code-block:: sh
+
+       kubectl get csr
+
+     The command's output resembles the following:
+
+     .. literalinclude:: /includes/code-examples/responses/k8s-cert-output.sh
+        :language: sh
+        :copyable: false
+        :start-after: START-output-k8s-rs-tls-csrs-approved
+        :end-before: END-output-k8s-rs-tls-csrs-approved
+
+  #. Repeat the following command for each host in your deployment to 
+     remove the |csrs|: 
+
+     .. code-block:: none
+
+        kubectl delete my-secure-rs-0.mongodb 
+
+     .. important::
+
+        Remove only the |tls| |csrs|. Don't remove X.509 or any other 
+        |csrs|.
+---
 title: Create a NodePort for each |k8s-pod|.
 level: 4
-stepnum: 1
+stepnum: 3
 ref: k8s-ext-rs-create-nodeports
 content: |
 
@@ -15,7 +59,7 @@ content: |
 ---
 title: Discover the dynamically assigned NodePorts.
 level: 4
-stepnum: 2
+stepnum: 4
 ref: k8s-ext-rs-discover-nodeports
 content: |
 
@@ -30,16 +74,13 @@ content: |
      <my-replica-set>-svc                    ClusterIP   None             <none>        27017/TCP                    38m
 
   NodePorts range from 30000 to 32767, inclusive.
-
 ---
 title: "Open your replica set resource |yaml| file."
 level: 4
-stepnum: 3
+stepnum: 5
 ref: open-replset-resource
-content: |
-
 ---
-stepnum: 4
+stepnum: 6
 ref: copy-k8s-example-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -60,15 +101,14 @@ replacement:
 
     .. literalinclude:: /includes/code-examples/yaml-files/example-replica-set.yaml
        :language: yaml
-       :start-after: START-horizon-addcert-replset-lower
-       :end-before: END-horizon-addcert-replset-lower
+       :start-after: START-horizon-addcert-replset-random-ports
+       :end-before: END-horizon-addcert-replset-random-ports
        :linenos:
        :lineno-start: 15
        :emphasize-lines: 1-8
-
 ---
 level: 4
-stepnum: 5
+stepnum: 7
 ref: paste-k8s-example-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -79,26 +119,29 @@ replacement:
 ---
 title: "Change the highlighted settings to your preferred values."
 level: 4
-stepnum: 6
+stepnum: 8
 ref: change-replset-resource
 content: |
 
   .. include:: /includes/list-tables/resource-keys-split-horizons.rst
 
 ---
-title: Add the ports for external connectivity.
+title: Confirm the external hostnames and NodePort values in your replica set resource.
 level: 4
-stepnum: 7
-ref: k8s-ext-rs-update-ports
+stepnum: 9
+ref: k8s-ext-rs-confirm-hostnames
 content: |
 
-  Set the ports to the NodePort values that you set for the
-  ``example-website`` connectivity setting.
+  Confirm that the external hostnames in the 
+  :setting:`spec.connectivity.replicaSetHorizons` setting are correct.
 
   External hostnames should match the |dns| names of |k8s| worker
   nodes. These can be *any* nodes in the |k8s| cluster. |k8s-nodes| do
   internal routing if the pod is run on another node.
 
+  Set the ports in :setting:`spec.connectivity.replicaSetHorizons` to 
+  the NodePort values that you discovered.
+
   .. example::
 
      .. literalinclude:: /includes/code-examples/yaml-files/example-replica-set.yaml
@@ -109,15 +152,9 @@ content: |
         :lineno-start: 15
         :emphasize-lines: 6-8
 
-  .. note::
-
-     You may need to delete each |k8s-pod|, then change the horizon
-     values, and then reapply. |k8s-op-short| then reconfigures the
-     horizons.
-
 ---
 level: 4
-stepnum: 8
+stepnum: 10
 ref: save-object-spec-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
@@ -126,28 +163,47 @@ replacement:
   k8sResource: :term:`replica set`
 ---
 level: 4
-stepnum: 9
-ref: start-k8s-deployment-rs
+stepnum: 11
+ref: restart-k8s-deployment-rs
 source:
   file: steps-source-deploy-k8s-resource.yaml
   ref: restart-k8s-deployment
 replacement:
   k8sResource: :term:`replica set`
   k8sResourceType: replica-set
 ---
+stepnum: 12
 level: 4
-stepnum: 10
-ref: track-k8s-deployment-rs
+ref: check-k8s-deployment-rs-tls
 source:
   file: steps-source-deploy-k8s-resource.yaml
-  ref: track-k8s-deployment-basic
+  ref: check-k8s-deployment
+---
+stepnum: 13
+level: 4
+ref: get-csrs-rs-tls
+source:
+  file: steps-source-deploy-k8s-resource.yaml
+  ref: get-csrs
 replacement:
-  k8sResource: :term:`replica set`
-
+  k8sResource: replica set
+  startTag: START-output-k8s-rs-tls-csrs
+  endTag: END-output-k8s-rs-tls-csrs
+---
+stepnum: 14
+level: 4
+ref: approve-csrs-rs-tls
+source:
+  file: steps-source-deploy-k8s-resource.yaml
+  ref: approve-host-csrs
+replacement:
+  k8sResource: replica set
+  startTag: START-input-k8s-rs-csrs
+  endTag: END-input-k8s-rs-csrs
 ---
 title: Test the connection to the replica set.
 level: 4
-stepnum: 11
+stepnum: 15
 ref: k8s-ext-rs-test-conn
 content: |
 

source/tutorial/connect-from-outside-k8s.txt

@@ -62,17 +62,6 @@ from outside of the |k8s| cluster depends on the resource.
          external connectivity. Other utilities can be used in
          production.
 
-      This procedure uses the following example:
-
-      .. literalinclude:: /includes/code-examples/yaml-files/example-replica-set.yaml
-         :language: yaml
-         :start-after: START-horizon-addcert-replset
-         :end-before: END-horizon-addcert-replset
-         :linenos:
-         :lineno-start: 1
-         :copyable: false
-         :emphasize-lines: 16-22
-
       To connect to your |k8s-op-short|-deployed MongoDB replica set
       resource from outside of the |k8s| cluster: