Navigation

Quick Start Procedure

Before you begin, learn about multi-cluster deployments implementation, multi-cluster services and tools <multi-cluster-services-tools-ref>, and complete the prerequisite steps:

Note

The following procedure scopes your multi-cluster deployment to a single namespace named mongodb. You can set scope for your deployment and use another namespace, multiple, or all namespaces.

1

Clone the MongoDB Enterprise Kubernetes Operator repository.

git clone https://github.com/mongodb/mongodb-enterprise-kubernetes.git
2

Run the multi-cluster kubeconfig creator tool.

By default, the Kubernetes Operator is scoped to the mongodb namespace. The following command creates one central cluster, three member clusters, and a namespace labeled mongodb in each of the clusters.

  1. Change to the directory to which you cloned the Kubernetes Operator repository, and then to the directory that has the multi-cluster kubeconfig creator tool.

  2. Run the multi-cluster kubeconfig creator tool:

    cd tools/multicluster
    go run main.go \
      -central-cluster="${MDB_CENTRAL_CLUSTER_FULL_NAME}" \
      -member-clusters="${MDB_CLUSTER_1_FULL_NAME},${MDB_CLUSTER_2_FULL_NAME},${MDB_CLUSTER_3_FULL_NAME}" \
      -member-cluster-namespace="mongodb" \
      -central-cluster-namespace="mongodb"
    
3

Set the Istio injection webhook in each member cluster.

Run the following command on the central cluster, specifying the context for each of the member clusters in the deployment. These commands add the istio-injection=enabled label to the mongodb namespace on each member cluster. This label configures Istio’s injection webhook which enables adding a sidecar to any Pods that you create in this namespace. To learn more, see Automatic sidecar injection in the Istio documentation.

kubectl label \
  --context=$MDB_CLUSTER_1_FULL_NAME \
  namespace mongodb \
  istio-injection=enabled
kubectl label \
  --context=$MDB_CLUSTER_2_FULL_NAME \
  namespace mongodb \
  istio-injection=enabled
kubectl label \
  --context=$MDB_CLUSTER_3_FULL_NAME \
  namespace mongodb \
  istio-injection=enabled
4

Configure kubectl to use the central cluster’s namespace.

If you have not done so already, run the following commands to run all kubectl commands on the central cluster in the default namespace. In the following steps, you will install the Kubernetes Operator into this namespace.

kubectl config use-context $MDB_CENTRAL_CLUSTER_FULL_NAME
kubectl config set-context $(kubectl config current-context) \
  --namespace=mongodb
5

Add the MongoDB Helm Charts for Kubernetes repository to Helm.

helm repo add mongodb https://mongodb.github.io/helm-charts
6

Install the MongoDB Enterprise Kubernetes Operator in the central cluster.

Use the MongoDB Helm Charts for Kubernetes for multi-cluster deployments to install Kubernetes Operator for managing your multi-cluster deployment:

helm upgrade \
  --install \
    mongodb-enterprise-operator-multi-cluster \
    mongodb/enterprise-operator \
      --namespace mongodb \
      --set namespace=mongodb \
      --version <mongodb-kubernetes-operator-version> \
      --set operator.name=mongodb-enterprise-operator-multi-cluster \
      --set operator.createOperatorServiceAccount=false \
      --set "multiCluster.clusters=$MDB_CLUSTER_1_FULL_NAME,$MDB_CLUSTER_2_FULL_NAME,$MDB_CLUSTER_3_FULL_NAME"
7

Deploy the MongoDB resource.

  1. On the central cluster, create a secret so that the Kubernetes Operator can create and update objects in your Ops Manager project. To learn more, see Create Credentials for the Kubernetes Operator.

  2. On the central cluster, create a ConfigMap to link the Kubernetes Operator to your Ops Manager project. To learn more, see Create One Project using a ConfigMap.

  3. On the central cluster, configure the required service accounts for each member cluster:

    helm template --show-only \
      templates/database-roles.yaml \
      mongodb/enterprise-operator \
      --set namespace=mongodb | \
    kubectl apply -f - \
      --context=$MDB_CLUSTER_1_FULL_NAME \
      --namespace mongodb
    
    helm template --show-only \
      templates/database-roles.yaml \
      mongodb/enterprise-operator \
      --set namespace=mongodb | \
    kubectl apply -f - \
      --context=$MDB_CLUSTER_2_FULL_NAME \
      --namespace mongodb
    
    helm template --show-only \
      templates/database-roles.yaml \
      mongodb/enterprise-operator \
      --set namespace=mongodb | \
    kubectl apply -f - \
      --context=$MDB_CLUSTER_3_FULL_NAME \
      --namespace mongodb
    
  4. Set spec.credentials and spec.opsManager.configMapRef.name and deploy the MongoDB resource. In the following code sample, duplicateServiceObjects is set to true to enable DNS proxying in Istio.

    Note

    To enable the cross-cluster DNS resolution by the Istio service mesh, this tutorial creates service objects with a single ClusterIP address per each Kubernetes Pod.

    kubectl apply -f - <<EOF
    apiVersion: mongodb.com/v1
    kind: MongoDBMulti
    metadata:
     name: multi-replica-set
    spec:
     version: 4.4.0-ent
     type: ReplicaSet
     persistent: false
     duplicateServiceObjects: true
     credentials: my-credentials
     opsManager:
       configMapRef:
         name: my-project
     clusterSpecList:
       clusterSpecs:
       - clusterName: ${MDB_CLUSTER_1_FULL_NAME}
         members: 3
       - clusterName: ${MDB_CLUSTER_2_FULL_NAME}
         members: 2
       - clusterName: ${MDB_CLUSTER_3_FULL_NAME}
         members: 3
    EOF
    
8

Verify that the MDB resources are running.

  1. For member clusters, run the following commands to verify that the MongoDB Pods are in the running state:

    kubectl get pods \
     --context=$MDB_CLUSTER_1_FULL_NAME \
     --namespace mongodb
    
    kubectl get pods \
     --context=$MDB_CLUSTER_2_FULL_NAME \
     --namespace mongodb
    
    kubectl get pods \
     --context=$MDB_CLUSTER_3_FULL_NAME \
     --namespace mongodb
    
  2. In the central cluster, run the following commands to verify that the MongoDBMulti custom resource is in the running state:

    kubectl --context=$MDB_CENTRAL_CLUSTER_FULL_NAME \
      --namespace mongodb \
      get mdbm multi-replica-set -o yaml -w