(DOCSP-28529) Includes full-fledged guide info. (#1295)

* (DOCSP-28529) Includes full-fledged guide info.

* Revises per tech and copy reviews.

* Revises per copy review.

* Fixes step formatting in step file.

Author: erabil-mdb

conf.py

@@ -122,6 +122,7 @@
     '.. |global-write| replace:: Global Writes',
     '.. |hardlink| replace:: https://www.mongodb.com/docs/kubernetes-operator/',
     '.. |hashicorp-vault| replace:: `HashiCorp Vault <https://www.vaultproject.io/>`__',
+    '.. |helm| replace:: `Helm <https://helm.sh/>`__',
     '.. |https| replace:: :abbr:`HTTPS (Hypertext Transfer Protocol Secure)`',
     '.. |http| replace:: :abbr:`HTTP (Hypertext Transfer Protocol)`',
     '.. |iana| replace:: :abbr:`IANA (Internet Assigned Numbers Authority)`',

source/includes/facts/fact-istio.rst

@@ -1,12 +1,7 @@
 In addition, we offer the :github:`install_istio_separate_network example script
-</mongodb/mongodb-enterprise-kubernetes/blob/master/tools/multicluster/install_istio_separate_network.sh>`.
-This script is based on Istio documentation and provides an example installation
-that uses the `multi-primary mode on different networks <https://istio.io/latest/docs/setup/install/multicluster/multi-primary_multi-network/>`__.
-
-We don't guarantee the script's maintenance with future Istio releases.
-If you choose to use the script, review the latest Istio documentation for
+</mongodb/mongodb-enterprise-kubernetes/blob/master/tools/multicluster/install_istio_separate_network.sh>`. This script is based on Istio documentation and provides an example installation
+that uses the `multi-primary mode on different networks <https://istio.io/latest/docs/setup/install/multicluster/multi-primary_multi-network/>`__. We don't guarantee the script's maintenance with future Istio releases. If you choose to use the script, review the latest Istio documentation for
 `installing a multicluster <https://istio.io/latest/docs/setup/install/multicluster/>`__,
 and, if necessary, adjust the script to match the documentation and your deployment.
-
 If you use another service mesh solution, create your own script for
 configuring separate networks to facilitate DNS resolution.

source/includes/install/verify-meko-installation.rst

@@ -0,0 +1,16 @@
+To verify that the |k8s-op-short| installed correctly, run the 
+following command and verify the output:
+
+.. code-block:: sh
+
+   kubectl describe deployments mongodb-enterprise-operator -n <metadata.namespace>
+
+By default, deployments exist in the ``mongodb`` namespace. If the 
+following error message appears, ensure you use the correct 
+namespace:
+
+.. code-block:: sh
+
+   Error from server (NotFound): deployments.apps "mongodb-enterprise-operator" not found
+
+.. include:: /includes/troubleshoot-k8s.rst

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

@@ -1,74 +1,40 @@
-- To enable internal cluster authentication, create |tls| certificates for
-  member clusters in the |multi-cluster|. 
 
-  .. tabs::
+.. note::
 
-     .. tab:: With Service Mesh
-        :tabid: with-sm
+   You must possess the |certauth| certificate and the key that you used to
+   sign your |tls| certificates.
 
-        Use one of the following options:
+.. tabs::
 
-        - Generate a wildcard |tls| certificate that covers hostnames
-          of the services that the |k8s-op-short| creates for each Pod
-          in the deployment.
+   .. tab:: With Service Mesh
+      :tabid: with-sm
 
-          If you generate wildcard certificates, you can continue using
-          the same certificates when you scale up or rebalance nodes in
-          the |k8s| member clusters, for example for :ref:`disaster recovery <disaster-recovery-ref>`.
+      .. include:: /includes/steps/add-tls-service-mesh.rst
 
-          For example, add the hostname similar to the following format
-          to the |san-dns|:
+   .. tab:: With Service Mesh (via script)
+      :tabid: via-script
 
-          .. code-block:: sh
+      To speed up creating |tls| certificates for member |k8s| clusters,
+      we offer the :github:`setup_tls script </mongodb/mongodb-enterprise-kubernetes/blob/master/tools/multicluster/setup_tls.sh>`. We don't guarantee the script's maintenance. If you choose to use the script,
+      test it and adjust it to your needs. The script does the following:
 
-             *.<namespace>.svc.cluster.local
+      - Creates the ``cert-manager`` namespace in the connected cluster and installs `cert-manager <https://cert-manager.io/docs/>`__ using |helm| in the ``cert-manager`` namespace.
 
-        - For each |k8s| service that the |k8s-op-short| generates corresponding
-          to each Pod in each member cluster, add |san-dns|\s to the certificate.
-          In your |tls| certificate, the |san-dns| for each |k8s| service must
-          use the following format:
+      - Installs a local |certauth| using `mkcert <https://github.com/FiloSottile/mkcert>`__.
 
-          .. include:: /includes/prereqs/san-format-multi-cluster.rst
+      - Downloads |tls| certificates from ``downloads.mongodb.com`` and concatenates them with the |certauth| file name and ``ca-chain``.
 
-     .. tab:: Without Service Mesh
-        :tabid: without-sm
+      - Creates a ConfigMap that includes the ``ca-chain`` files.
 
-        Use one of the following options:
+      - Creates an ``Issuer`` resource, which cert-manager uses to generate certificates.
 
-        - Generate a wildcard |tls| certificate that contains all
-          :ref:`externalDomains <multi-spec-clusterspeclist-externaldomain>`
-          that you created in the |san-dns|. For example, add the hostnames
-          similar to the following format to the |san-dns|:
+      - Creates a ``Certificate`` resource, which cert-manager uses to create a key object for the certificates.
 
-          .. code-block:: sh
-         
-             *.cluster-0.example.com, *.cluster-1.example.com
+      To use the script:
 
-          If you generate wildcard certificates, you can continue using
-          them when you scale up or rebalance nodes in the |k8s| member
-          clusters, for example for :ref:`disaster recovery <disaster-recovery-ref>`.
+      .. include:: /includes/steps/add-tls-script.rst
 
-        - Generate a |tls| certificate for each MongoDB replica set member
-          hostname in the |san-dns|. For example, add the hostnames similar
-          to the following to the |san-dns|:
+   .. tab:: Without Service Mesh
+      :tabid: without-sm
 
-          .. code-block:: sh
-    
-             my-replica-set-0-0.cluster-0.example.com,
-             my-replica-set-0-1.cluster-0.example.com, 
-             my-replica-set-1-0.cluster-1.example.com,
-             my-replica-set-1-1.cluster-1.example.com
-
-          If you generate an individual |tls| certificate that contains
-          all the specific hostnames, you must create a new certificate
-          each time you scale up or rebalance nodes in the |k8s| member
-          clusters, for example for :ref:`disaster recovery <disaster-recovery-ref>`.
-
-- Generate one TLS certificate for your project's MongoDB Agents.
-
-  .. include:: /includes/prereqs/mdbagent-reqs-multi-cluster.rst
-
-- You must possess the |certauth| certificate and the key that you used to
-  sign your |tls| certificates.
-
-.. include:: /includes/prereqs/pem-format.rst
+      .. include:: /includes/steps/add-tls-without-service-mesh.rst

source/includes/prereqs/mdbagent-reqs-multi-cluster.rst

@@ -0,0 +1,33 @@
+---
+stepnum: 1
+level: 4
+ref: install-mkcert-prereqs
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: install-mkcert
+
+---
+stepnum: 2
+level: 4
+ref: set-context-central-cluster-prereqs
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: set-context-central-cluster
+
+---
+stepnum: 3
+level: 4
+ref: run-tls-script-prereqs
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: run-tls-script
+
+---
+stepnum: 4
+level: 4
+ref: generate-tls-agents-script
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: generate-tls-agents
+
+...

source/includes/steps-add-tls-script.yaml

@@ -0,0 +1,17 @@
+---
+stepnum: 1
+level: 4
+ref: generate-tls-services-prereq
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: generate-tls-services
+
+---
+stepnum: 2
+level: 4
+ref: generate-tls-agents-prereq
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: generate-tls-agents
+
+...

source/includes/steps-add-tls-service-mesh.yaml

@@ -0,0 +1,17 @@
+---
+stepnum: 1
+level: 4
+ref: generate-tls-san-hostnames-prereqs
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: generate-tls-san-hostnames
+
+---
+stepnum: 2
+level: 4
+ref: generate-tls-agents-no-mesh
+inherit:
+  file: steps-multi-cluster-source.yaml
+  ref: generate-tls-agents
+
+...

source/includes/steps-add-tls-without-service-mesh.yaml

@@ -23,7 +23,7 @@ content: |
 
   .. note::
 
-     You can use `Helm <https://helm.sh/>`__ to install the
+     You can use |helm| to install the
      |k8s-op-short|. To learn how to install Helm, see its
      :github:`documentation on GitHub </kubernetes/helm>`.
 

source/includes/steps-install-prereqs.yaml

@@ -15,62 +15,38 @@ source:
 ---
 stepnum: 3
 level: 4
-ref: clone-k8s-qs
-inherit:
-  file: steps-multi-cluster-source.yaml
-  ref: clone-k8s-repo-multi-cluster
-
----
-stepnum: 4
-level: 4
 ref: run-plugin-qs
 inherit:
   file: steps-multi-cluster-source.yaml
   ref: run-kubectl-mongodb
 
 ---
-stepnum: 5
+stepnum: 4
 level: 4
 ref: set-istio-webhook-qs
 inherit:
   file: steps-multi-cluster-source.yaml
   ref: set-istio-webhook
 
 ---
-stepnum: 6
+stepnum: 5
 level: 4
 ref: configure-kubectl-mc-qs
 inherit:
   file: steps-multi-cluster-source.yaml
   ref: configure-kubectl-mc
 
 ---
-stepnum: 7
-level: 4
-ref: install-mc-helm-charts
-inherit:
-  file: steps-multi-cluster-source.yaml
-  ref: install-helm-charts
-
----
-stepnum: 8
-level: 4
-ref: install-kubectl-mc-qs
-inherit:
-  file: steps-multi-cluster-source.yaml
-  ref: install-kubectl-mc
-
----
-stepnum: 9
+stepnum: 6
 level: 4
-title: "Configure service accounts and roles for each member cluster."
-ref: configure-mc-service-accounts-qs
+title: "Deploy the |k8s-op-full| in the central cluster."
+ref: deploy-meko-mc-qs
 inherit:
   file: steps-multi-cluster-source.yaml
-  ref: configure-mc-service-accounts
+  ref: deploy-meko-central-cluster
 
 ---
-stepnum: 10
+stepnum: 7
 level: 4
 title: "Create a secret to use with Ops Manager and create a ConfigMap."
 ref: create-configmap-and-secret-qs
@@ -79,25 +55,25 @@ inherit:
   ref: create-configmap-and-secret
 
 ---
-stepnum: 11
+stepnum: 8
 level: 4
-title: "Deploy |onprem| on the central cluster."
+title: "Deploy |onprem| on the central cluster and connect to |onprem|."
 ref: deploy-om-cental-cluster-qs
 inherit:
   file: steps-multi-cluster-source.yaml
   ref: deploy-om-mc-central-cluster
 
 ---
-stepnum: 12
+stepnum: 9
 level: 4
-title: "Deploy the MongoDB resource."
+title: "Deploy the |mongodb-multi| resource."
 ref: deploy-mdbresource-mc-qs
 inherit:
   file: steps-multi-cluster-source.yaml
   ref: deploy-mdbresource-mc-tls
 
 ---
-stepnum: 13
+stepnum: 10
 level: 4
 ref: verify-mdb-resources-mc-qs
 inherit: