Merging the multi-cluster-ga branch into master (#1265)

* (DOCSP-27139) Deploy a multi-cluster replica set with statefulSet override (#1212)
* (DOCSP-27139) Deploy a multi-cluster replica set with statefulSet override
* Renamed the multi-cluster resource
* Refactoring, to make the prereqs apply to both quickstart and regular procedure
* (DOCSP-27918) Adds multi-cluster limitation for secret storage.
* (DOCSP-27855) Adds limitation for multi-cluster OM. Breaks out OM limitation and removes Vault references.
* (DOCSP-28415) Adds no Prometheus limitation.
* (DOCSP-27827) Describes new CLUSTER_CLIENT_TIMEOUT var for multi-cluster.
* (DOCSP-27653) Update Istio info, for GA (#1251)
* (DOCSP-27653) Istio updates for GA
* (DOCSP-27784) Renaming the MongoDBMulti to MongoDBMultiCluster (#1255)
* (DOCSP-27784) Renaming the MongoDBMulti to MongoDBMultiCluster. Removes the word "beta".
* (DOCSP-27759) Rename multi-cluster CLI to mongodb kubectl plugin, update plugin's options and add plugin install to prereqs (#1257)
* (DOCSP-28373) MEKO Multi-Cluster RBAC Configuration (#1259)
* (DOCSP-27825) OM in multi-clusters (#1261) and the OM HA limitation
* (DOCSP-28373-follow) Changing links to reflect eventual public file locations. (#1262)
* (DOCSP-27856) Adds multi-cluster resource specifications. (#1245)
* (DOCSP-27856) Adds multi-cluster CRD.
* (DOCSP-28445) Modify a MongoDBMultiCluster Resource (#1264)
* (DOCSP-28445) Modify a MongoDBMultiCluster Resource

---------

Co-authored-by: Evelyn Rabil <[email protected]>
Co-authored-by: lmkerbey-mdb <[email protected]>
Co-authored-by: Evelyn Rabil <[email protected]>

Author: 3 people

conf.py

@@ -147,6 +147,8 @@
     '.. |k8s-crd| replace:: `CustomResourceDefinition <https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/>`__',
     '.. |k8s-mdbrscs| replace:: MongoDB Kubernetes resources',
     '.. |k8s-mdbrsc| replace:: MongoDB Kubernetes resource',
+    '.. |mongodb-multi| replace:: ``MongoDBMultiCluster`` resource',
+    '.. |mongodb-multis| replace:: ``MongoDBMultiCluster`` resources',
     '.. |k8s-nodes| replace:: `nodes <https://kubernetes.io/docs/concepts/architecture/nodes/>`__',
     '.. |k8s-node| replace:: `node <https://kubernetes.io/docs/concepts/architecture/nodes/>`__',
     '.. |k8s-nss| replace:: `namespaces <https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/>`__',
@@ -192,9 +194,8 @@
     '.. |Multi-cluster| replace:: Multi-Kubernetes-cluster deployment',
     '.. |multi-clusters| replace:: multi-Kubernetes-cluster deployments',
     '.. |Multi-clusters| replace:: Multi-Kubernetes-cluster deployments',
-    '.. |mc-cli| replace:: multi-cluster CLI',
-    '.. |Mc-cli| replace:: Multi-cluster CLI',
     '.. |oc| replace:: :xml:`<mono><link target="https://docs.openshift.com/container-platform/4.12/cli_reference/index.html">oc</link></mono>`',
+    '.. |kubectl-mongodb| replace:: ``kubectl mongodb`` plugin',
     '.. |onprem| replace:: Ops Manager',
     '.. |onprem-link| replace:: :opsmgr:`Ops Manager </>`',
     '.. |nfs| replace:: :abbr:`NFS (Network File System)`',

config/redirects

@@ -12,6 +12,13 @@ symlink: stable -> v1.18
 # Base URL
 raw: docs/kubernetes-operator/ -> ${base}/stable/
 
+# Add redirects for the renaming of the multi-cluster CLI to MongoDB kubectl
+plugin, starting with version 1.19 and later:
+[v1.19-*]: docs/kubernetes-operator/${version}/multi-cluster-cli-reference -> ${base}/stable/plugin-reference/
+[v1.19-*]: docs/kubernetes-operator/${version}/multi-cluster-quick-start-prerequisites -> ${base}/stable/multi-cluster-prerequisites/
+[v1.19-*]: docs/kubernetes-operator/${version}/central-and-member-clusters -> ${base}/stable/multi-cluster/multi-cluster-overview/
+[*-v1.19]: docs/kubernetes-operator/${version}/tutorial/multi-cluster-edit-deployment -> ${base}/tutorial/multi-cluster-deploy-replica-set/
+
 # Add redirects for the complete removal of old-style tls certs and the EOL of MEKO # v1.11 that required special treatment of appdb version:
 [v1.17-*]: docs/kubernetes-operator/${version}/tutorial/migrate-to-ent-appdb-version -> ${base}/stable/release-notes/#k8s-op-full-1-11-0/
 [v1.17-*]: docs/kubernetes-operator/${version}/tutorial/migrate-to-new-tls-format -> ${base}/stable/release-notes/#k8s-op-full-1-13-0/

source/faq.txt

@@ -18,19 +18,19 @@ Frequently Asked Questions
 What is an Operator?
 --------------------
 
-An operator is a standard mechanism that extends the control plane of 
-|k8s| to managing custom |k8s| resources. Because each operator is 
-built for its own Custom Resources (CRs), it can contain logic that 
-addresses the type of service that the operator is built for. For the 
-|k8s-op-short|, the operator includes the logic for the deployment of 
+An operator is a standard mechanism that extends the control plane of
+|k8s| to managing custom |k8s| resources. Because each operator is
+built for its own Custom Resources (CRs), it can contain logic that
+addresses the type of service that the operator is built for. For the
+|k8s-op-short|, the operator includes the logic for the deployment of
 MongoDB Server and Ops Manager instances.
 
 Each CR used by the |k8s-op-short| represents an element of a MongoDB 
 Server deployment in |k8s|, and has options for customizing that part
 of the deployment. Once you configure these objects in the |k8s| 
 deployment, the operator builds native |k8s| objects, such as Stateful 
 Sets that are necessary to create Pods according to your specified 
-requirements for MongoDB Servers. The operator also facilitates 
+requirements for MongoDB Servers. The |k8s-op-short| also facilitates
 configuration of MongoDB Server features, such as database backups, 
 through interaction with |cloud| or |onprem|.
 
@@ -41,41 +41,35 @@ When you deploy MongoDB Server or MongoDB Enterprise Advanced in |k8s|
 through the |k8s-op-full|, your deployments can benefit from the 
 resilience and simple orchestration that |k8s| provides.
 
-The only supported way to deploy MongoDB Enterprise Advanced in |k8s| is 
-through the |k8s-op-full|. The |k8s-op-full| simplifies your daily 
-workflows and makes it easier for MongoDB technical support staff to 
-assist you when needed.
+The only supported way to deploy MongoDB Enterprise Advanced in |k8s| is
+through the |k8s-op-full|. The |k8s-op-full| simplifies your daily workflows
+and makes it easier for MongoDB technical support staff to assist you when needed.
 
 Which |k8s| platforms are supported for MongoDB Server deployments?
 -------------------------------------------------------------------------
 
-MongoDB Server supports any platform that builds upon native |k8s| 
-without changing the default logic or behavior. In practice, this means
-that MongoDB Server supports any |k8s| platform 
-`certified by the Cloud Native Computing Foundation <https://www.cncf.io/certification/software-conformance/>`_. 
-To learn more, see 
-:ref:`MongoDB Kubernetes Operator Compatibility <k8s-compatibility>`.
+MongoDB Server supports any platform that builds upon native |k8s| without
+changing the default logic or behavior. In practice, this means that
+MongoDB Server supports any |k8s| platform
+`certified by the Cloud Native Computing Foundation <https://www.cncf.io/certification/software-conformance/>`__.
+To learn more, see :ref:`MongoDB Kubernetes Operator Compatibility <k8s-compatibility>`.
 
 How many deployments can |k8s-op-full| support?
 -----------------------------------------------
 
-|k8s-op-short| can support up to 50 deployments. However, changes made
-to large numbers of deployments at the same time result in long 
-reconciliation times. To avoid prolonged reconciliation times, limit a
-given |k8s-op-short| instance to 20 deployments. To learn more, 
-see the :ref:`production notes <deploy_recommended-number-sets>`.
+|k8s-op-short| can support up to 50 deployments. However, changes made to
+large numbers of deployments at the same time result in long reconciliation times.
+To avoid prolonged reconciliation times, limit a given |k8s-op-short| instance
+to 20 deployments. To learn more, see the :ref:`production notes <deploy_recommended-number-sets>`.
 
 Should I run MongoDB Server in |k8s| in the same cluster as the application using it?
 --------------------------------------------------------------------------------------
 
-To help minimize latency, consider colocating your database and 
-applications on the same |k8s| cluster if your deployment architecture
-allows this.
+To help minimize latency, consider colocating your database and applications on
+the same |k8s| cluster if your deployment architecture allows this.
 
 Can I deploy MongoDB Server across multiple |k8s| clusters?
 -----------------------------------------------------------
 
-This feature is available in Beta releases, as described in 
-:ref:`Deploy MongoDB Resources on Multiple Kubernetes Clusters <multi-cluster>`.
-To learn more, 
-`contact Support <https://cloud.mongodb.com/links/support>`_.
+Yes. To learn more, see :ref:`Deploy MongoDB Resources on Multiple Kubernetes Clusters <multi-cluster>`.
+For help, `contact MongoDB Support <https://cloud.mongodb.com/links/support>`__.

source/includes/admonitions/note-om-context-scope-multi-cluster.rst

@@ -0,0 +1,8 @@
+If you are deploying an |onprem| resource on a |multi-cluster|:
+
+- Set the ``context`` to the name of the central cluster, such as:
+  ``kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME"``.
+
+- Set the ``--namespace`` to the same :ref:`scope <mc-namespace-scope-ref>`
+  that you used for your |multi-cluster|, such as: ``kubectl config --namespace "mongodb"``.
+

source/includes/admonitions/note-om-external-connectivity-multi-cluster.rst

@@ -0,0 +1,24 @@
+To connect member clusters to the |onprem| resource's deployment in the
+central cluster in a |multi-cluster|, use one of the following methods:
+
+- Set the :opsmgrkube:`spec.externalConnectivity` to ``true`` and specify
+  the |onprem| port in it. Use the :github:`ops-manager-external.yaml
+  </mongodb/mongodb-enterprise-kubernetes/blob/master/samples/ops-manager/ops-manager-external.yaml>`
+  example script, modify it to your needs, and apply the configuration.
+  For example, run:
+
+  .. code-block:: sh
+
+     kubectl apply \
+      --context "$MDB_CENTRAL_CLUSTER_FULL_NAME" \
+      --namespace "mongodb" \
+       -f https://raw.githubusercontent.com/mongodb/mongodb-enterprise-kubernetes/master/samples/ops-manager/ops-manager-external.yaml
+
+- Add the central cluster and all member clusters to the service mesh.
+  The service mesh establishes communication from the central and all
+  member clusters to the |onprem| instance. To learn more, see the
+  :ref:`Multi-Kubernetes-Cluster Quick Start <multi-cluster-quick-start-ref>`
+  procedures and see the step that references the ``istio-injection=enabled``
+  label for Istio. Also, see `Automatic sidecar injection
+  <https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection>`__
+  in the Istio documentation.

source/includes/admonitions/note-om-kubectl-apply-multi-cluster.rst

@@ -0,0 +1,8 @@
+If you are deploying an |onprem| resource on a |multi-cluster|, run:
+
+.. code-block:: sh
+
+    kubectl apply \
+      --context "$MDB_CENTRAL_CLUSTER_FULL_NAME" \
+      --namespace "mongodb" 
+       -f https://raw.githubusercontent.com/mongodb/mongodb-enterprise-kubernetes/master/samples/ops-manager/ops-manager-external.yaml

source/includes/check-resource-status-multi-cluster.rst

@@ -0,0 +1,9 @@
+To check the status of your |mongodb-multi|, use the following command on the central cluster:
+
+.. code-block:: sh
+
+   kubectl get mdbm <resource-name> -o yaml -w
+
+With the ``-w`` (watch) flag set, when the configuration changes, the output
+refreshes immediately until the status phase achieves the ``Running`` state.
+To learn more about resource deployment statuses, see :doc:`/reference/troubleshooting`.

source/includes/check-resource-status.rst

@@ -1,13 +1,10 @@
-To check the status of your |k8s-mdbrsc|, invoke the following
+To check the status of your |k8s-mdbrsc|, use the following
 command:
 
 .. code-block:: sh
 
    kubectl get mdb <resource-name> -o yaml -w
 
-The ``-w`` flag means "watch". With the "watch" flag set, the output
-refreshes immediately when the configuration changes until the status phase
-achieves the ``Running`` state.
-
-See :doc:`/reference/troubleshooting` for information about the resource
-deployment statuses.
+With the ``-w`` (watch) flag set, when the configuration changes, the output
+refreshes immediately until the status phase achieves the ``Running`` state.
+To learn more about resource deployment statuses, see :doc:`/reference/troubleshooting`.

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

@@ -0,0 +1,73 @@
+
+# Provides statefulSet override per cluster
+
+apiVersion: mongodb.com/v1
+kind: MongoDBMultiCluster
+metadata:
+  name: multi-replica-set
+spec:
+  version: 4.4.0-ent
+  type: ReplicaSet
+  duplicateServiceObjects: false
+  credentials: my-credentials
+  opsManager:
+    configMapRef:
+      name: my-project
+  clusterSpecList:
+    - clusterName: cluster1.example.com
+      members: 2
+      statefulSet:
+        spec:
+          template:
+            spec:
+              containers:
+              - name: sidecar1
+                image: busybox
+                command: [ "sleep" ]
+                args: [ "infinity" ]
+          # Use to override the default storage size of the "data" Persistent Volume
+          volumeClaimTemplates:
+          - metadata:
+              name: data
+            spec:
+              resources:
+                requests:
+                  storage: 1Gi
+    - clusterName: cluster2.example.com
+      members: 1
+      statefulSet:
+        spec:
+          template:
+            spec:
+              containers:
+              - name: sidecar2
+                image: busybox
+                command: [ "sleep" ]
+                args: [ "infinity" ]
+            volumeClaimTemplates:
+            - metadata:
+                name: data
+              spec:
+                resources:
+                  requests:
+                    storage: 1Gi
+    - clusterName: cluster3.example.com
+      members: 1
+      statefulSet:
+        spec:
+          template:
+            spec:
+              containers:
+              - name: sidecar3
+                image: busybox
+                command: [ "sleep" ]
+                args: [ "infinity" ]
+            volumeClaimTemplates:
+            - metadata:
+                name: data
+              spec:
+                resources:
+                  requests:
+                    storage: 1Gi
+
+...

source/includes/code-examples/yaml-files/example-watch-namespaces-env-helm.yaml

@@ -1,7 +1,6 @@
 .. example::
 
    .. code-block:: yaml
-      :emphasize-lines: 3
 
       # Operator with name `mongodb-enterprise-operator-qa-envs` will
       # watch ns-dev, ns-qa and ns-uat namespaces

source/includes/code-examples/yaml-files/example-watch-namespaces-staging-only-helm.yaml

@@ -1,7 +1,6 @@
 .. example::
 
    .. code-block:: yaml
-      :emphasize-lines: 3
 
       # Operator with name `mongodb-enterprise-operator-staging` will
       # watch ns-staging and ns-pre-prod

source/includes/code-examples/yaml-files/example-watch-one-namespace-helm.yaml

@@ -1,7 +1,6 @@
 .. example::
 
    .. code-block:: yaml
-      :emphasize-lines: 2
 
       # Watch one namespace
       helm install enterprise-operator mongodb/enterprise-operator \

source/includes/code-examples/yaml-files/example-watch-two-namespaces-helm.yaml

@@ -1,7 +1,6 @@
 .. example::
 
    .. code-block:: yaml
-      :emphasize-lines: 2
 
       # Watch both namespace-a and namespace-b
       helm install enterprise-operator mongodb/enterprise-operator \

source/includes/facts/fact-central-member-clusters.rst

@@ -0,0 +1,12 @@
+A |multi-cluster| that uses the |k8s-op-full| consists of one
+**central cluster** and one or more **member clusters** in |k8s|:
+
+- The **central cluster** has the following role:
+
+  - Hosts the |k8s-op-full|
+  - Acts as the control plane for the |multi-cluster|
+  - Hosts the |mongodb-multi| spec for the MongoDB replica set
+  - Hosts |onprem|, if you deploy |onprem| with the |k8s-op-short|
+  - Can also host members of the MongoDB replica set
+
+- **Member clusters** host the MongoDB replica sets.

source/includes/facts/fact-custom-resource-intro.rst

@@ -0,0 +1,14 @@
+The :github:`MongoDB Enterprise Kubernetes Operator </mongodb/mongodb-enterprise-kubernetes>`
+creates |k8s| |k8s-statefulsets| from specification files that you write.
+
+The |k8s-op-short| creates MongoDB-specific resources in |k8s| as
+:k8sdocs:`custom resources </concepts/extend-kubernetes/api-extension/custom-resources/>`.
+
+To manage these custom resources, use the following process:
+
+1. Create or update a |k8s-mdbrsc| specification.
+2. Direct |k8s-op-full| to apply it to your |k8s| environment.
+   As a result, |k8s-op-short| performs these actions:
+
+   - Creates the defined |k8s-statefulsets|, services and other |k8s| resources.
+   - Updates the |onprem-link| deployment configuration to reflect changes.

source/includes/facts/fact-istio.rst

@@ -0,0 +1,12 @@
+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
+`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/facts/fact-multi-cluster-cli-actions-setup.rst

@@ -0,0 +1,4 @@
+Use the |kubectl-mongodb| to:
+
+- :ref:`Set up multi-Kubernetes-cluster Deployments <multi-cluster-quick-start-ref>`
+- :ref:`Run automatic and manual disaster recovery <disaster-recovery-ref>`

source/includes/facts/fact-multi-cluster-plugin-about.rst

@@ -0,0 +1,7 @@
+- Creates a default ConfigMap named ``mongodb-enterprise-operator-member-list``
+  that contains all the member clusters of the |multi-cluster|. This name is
+  hard-coded and you can't change it. See :ref:`Known Issues <hardcoded_configmap_multi-clusters>`.
+- Creates |k8s-service-accounts|, Roles, and RoleBindings in the central
+  cluster and each member cluster.
+- Applies the correct permissions for service accounts.
+- Uses the preceding settings to create your |multi-cluster|.

source/includes/facts/fact-multi-cluster-plugin-actions-setup.rst

@@ -0,0 +1,19 @@
+To deploy an |onprem| instance in the central cluster and connect to it,
+use the following procedures:
+
+- :ref:`Review the Ops Manager resource architecture <meko-om-arch>`
+- :ref:`Review the Ops Manager resource considerations and prerequisites <plan-om-resource>`
+- :ref:`Deploy an Ops Manager instance on the central cluster with TLS encryption <deploy-om-container>`
+
+These procedures are the same as the procedures for single clusters
+deployed with the |k8s-op-short| with the following exceptions:
+
+- Run the procedures to deploy |onprem| only on the central cluster of your |multi-cluster|.
+
+- Set the context and the |k8s-ns|.
+
+  .. include:: /includes/admonitions/note-om-context-scope-multi-cluster.rst
+
+- Configure external connectivity for |onprem|.
+
+  .. include:: /includes/admonitions/note-om-external-connectivity-multi-cluster.rst

source/includes/facts/fact-om-in-multi-clusters-summary-of-diffs.rst

@@ -1,3 +1,3 @@
 Required. Namespace that the |k8s-op-short|
 will be deployed to, such as:
-``-central-cluster-namespace="mongodb"``.
+``--central-cluster-namespace="mongodb"``.

source/includes/list-tables/multi-cluster-cli-central-cluster.rst

@@ -0,0 +1,3 @@
+Required. Central cluster that the |k8s-op-short|
+will be deployed in, such as:
+``--central-cluster="MDB_CENTRAL_CLUSTER_FULL_NAME"``.