Navigation

Quick Start Procedure

On this page

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

Note

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

Considerations

When you create a multi-Kubernetes-cluster deployment with the Kubernetes Operator, you must choose whether to encrypt connections using TLS certificates.

The following procedure for TLS-Encrypted connections:

  • Establishes TLS-encrypted connections between MongoDB hosts in a replica set.
  • Establishes TLS-encrypted connections between client applications and MongoDB deployments.
  • Requires valid certificates for TLS encryption.

The following procedure for Non-Encrypted Connections:

  • Doesn’t encrypt connections between MongoDB hosts in a replica set.
  • Doesn’t encrypt connections between client applications and MongoDB deployments.
  • Has fewer setup requirements than a deployment with TLS-encrypted connections.

Select the appropriate tab based on whether you want to encrypt your replica set connections with TLS.

Deploy a MongoDBMulti Resource

1

Create the secret for the TLS certificate of your MongoDBMulti custom resource.

Run the kubectl command to create a new secret that stores the MongoDB multi-cluster resource’s certificate:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace=<metadata.namespace> \
  create secret tls <prefix>-<metadata.name>-cert \
  --cert=<resource-tls-cert> \
  --key=<resource-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name>.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

To learn about your options for secret storage, see Configure Secret Storage.

2
3

Clone the MongoDB Enterprise Kubernetes Operator repository.

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

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:

    copy 
    cd tools/multicluster
go run main.go \
setup
  -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"
5

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.

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

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.

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

Add the MongoDB Helm Charts for Kubernetes repository to Helm.

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

Install the MongoDB Enterprise Kubernetes Operator in the central cluster.

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

copy 
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"
9

Deploy the MongoDB resource.

  1. 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. Create a ConfigMap to link the Kubernetes Operator to your Ops Manager project. To learn more, see Create One Project using a ConfigMap.

  3. Configure the required service accounts for each member cluster:

    copy 
    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
    copy 
    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
    copy 
    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, spec.opsManagerconfigMapRef.name, and security settings 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.

    copy 
    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
 security:
   tls:
     ca: custom-ca
 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

The Kubernetes Operator copies the ConfigMap with the CA that you created in step 2 to each member cluster, generates a concatenated PEM secret, and distributes it to the member clusters.

10

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:

    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_1_FULL_NAME \
 --namespace mongodb
    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_2_FULL_NAME \
 --namespace mongodb
    copy 
    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:

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

Renew TLS Certificates for a MongoDBMulti Resource

Renew your TLS certificates periodically using the following procedure.

1

Renew the secret for a MongoDBMulti resource.

Run this kubectl command to renew an existing secret that stores the MongoDBMulti resource’s certificates:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
--namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-cert \
--cert=<resource-tls-cert> \
--key=<resource-tls-key> \
--dry-run=client \
-o yaml |
kubectl apply -f -

Deploy a MongoDBMulti Resource

1

Clone the MongoDB Enterprise Kubernetes Operator repository.

copy 
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:

    copy 
    cd tools/multicluster
go run main.go \
setup
  -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.

copy 
kubectl label \
  --context=$MDB_CLUSTER_1_FULL_NAME \
  namespace mongodb \
  istio-injection=enabled
copy 
kubectl label \
  --context=$MDB_CLUSTER_2_FULL_NAME \
  namespace mongodb \
  istio-injection=enabled
copy 
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.

copy 
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.

copy 
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-Kubernetes-cluster deployments to install Kubernetes Operator for managing your multi-Kubernetes-cluster deployment:

copy 
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:

    copy 
    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
    copy 
    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
    copy 
    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.

    copy 
    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:

    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_1_FULL_NAME \
 --namespace mongodb
    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_2_FULL_NAME \
 --namespace mongodb
    copy 
    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:

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

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.