- Deploy MongoDB Resources on Multiple Kubernetes Clusters >
- Multi-Kubernetes-Cluster Quick Start
Multi-Kubernetes-Cluster Quick Start¶
Use the quick start to deploy a MongoDB replica set across three Kubernetes member clusters, using GKE (Google Kubernetes Engine) and Istio service mesh.
Before you begin:
- Learn about multi-Kubernetes-cluster deployments
- Review the list of multi-Kubernetes-cluster services and tools
- Complete the prerequisites
Note
The following procedures scope your multi-Kubernetes-cluster deployment to a single
namespace named mongodb
. You can configure your multi-Kubernetes-cluster deployment to
watch resources in multiple namespaces
or all namespaces.
Prefer to Learn by Watching?¶
Follow along with this video tutorial walk-through that demonstrates how to create a multi-Kubernetes-cluster deployment.
Duration: 12 Minutes
Deploying a MongoDB Replica Set across Multiple Kubernetes Clusters
Deploy a MongoDBMultiCluster Resource¶
Select the appropriate tab based on whether you want to encrypt replica set connections in your multi-Kubernetes-cluster deployments using TLS certificates.
- With TLS-Encrypted Connections
- With Non-Encrypted Connections
You can use the following procedures in this TLS-Encrypted Connections tab:
- Deploy a
MongoDBMultiCluster
resource - Renew TLS Certificates for a
MongoDBMultiCluster
resource
These procedures establish TLS-encrypted connections between MongoDB hosts in a replica set, and between client applications and MongoDB deployments.
Before you begin, you must have valid certificates for TLS encryption.
Create the secret for the TLS certificate of your MongoDBMultiCluster
resource.¶
Run the kubectl
command to create a new secret that stores the
MongoDBMultiCluster
resource certificate:
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
.
Create the ConfigMap to link your CA with your MongoDBMultiCluster
resource.¶
Run the kubectl
command to link your CA to your MongoDBMultiCluster
resource.
Specify the CA certificate file that you must always name
ca-pem
for the MongoDBMultiCluster
resource:
Run the kubectl mongodb
plugin.¶
By default, the Kubernetes Operator is scoped to the mongodb
namespace. When you run the following command, the kubectl mongodb
plugin:
- Creates one central cluster, three member clusters, and a namespace labeled
mongodb
in each of the clusters. - Creates a default ConfigMap with the hard-coded name
mongodb-enterprise-operator-member-list
that contains all the member clusters. You can’t change the ConfigMap’s name. - Creates the service accounts and Roles required for running database workloads in the member clusters.
Run the kubectl mongodb
plugin:
Optional: Set the Istio injection webhook in each member cluster.¶
If you’re using Istio, 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.
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.
Deploy the MongoDB Enterprise Kubernetes Operator in the central cluster.¶
Deploy the MongoDB Enterprise Kubernetes Operator in the central cluster in the mongodb
namespace with Helm or kubectl
.
- Helm
- kubectl
Add the MongoDB Helm Charts for Kubernetes repository to Helm.
Use the MongoDB Helm Charts for Kubernetes to deploy the Kubernetes Operator.
Apply the Kubernetes Operator custom resources.
Download the Kubernetes Operator YAML template.
Optional: Customize the Kubernetes Operator YAML template.
To learn about optional Kubernetes Operator installation settings, see MongoDB Enterprise Kubernetes Operator kubectl and oc Installation Settings.
Apply the Kubernetes Operator YAML file.
Verify that the Kubernetes Operator is deployed.
To verify that the Kubernetes Operator installed correctly, run the following command and verify the output:
- Using kubectl
- Using oc
By default, deployments exist in the
mongodb
namespace. If the following error message appears, ensure you use the correct namespace:To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator and other troubleshooting topics.
Important
If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.
Create a secret to use with Ops Manager and create a ConfigMap.¶
- 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.
- Create a ConfigMap to link the Kubernetes Operator to your Ops Manager project. To learn more, see Create One Project using a ConfigMap.
Deploy Ops Manager on the central cluster and connect to Ops Manager.¶
Review the multi-Kubernetes-cluster deployment exceptions and follow the linked procedures in Deploy an Ops Manager Resource, deploy the Application Database, and Connect to Ops Manager.
Deploy the MongoDBMultiCluster
resource.¶
Set spec.credentials
,
spec.opsManagerconfigMapRef.name
, and
security settings
and deploy the MongoDBMultiCluster
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.
The Kubernetes Operator copies the ConfigMap with the CA that you created in previous steps to each member cluster, generates a concatenated PEM secret, and distributes it to the member clusters.
Verify that the MongoDBMultiCluster
resources are running.¶
For member clusters, run the following commands to verify that the MongoDB Pods are in the running state:
In the central cluster, run the following command to verify that the
MongoDBMultiCluster
resource is in the running state:
Renew TLS Certificates for a MongoDBMultiCluster Resource
Renew your TLS certificates periodically using the following procedure.
This procedure doesn’t encrypt connections between MongoDB hosts in a replica set, and between client applications and MongoDB deployments.
Run the kubectl mongodb
plugin.¶
By default, the Kubernetes Operator is scoped to the mongodb
namespace. When you run the following command, the kubectl mongodb
plugin:
- Creates one central cluster, three member clusters, and a namespace labeled
mongodb
in each of the clusters. - Creates a default ConfigMap with the hard-coded name
mongodb-enterprise-operator-member-list
that contains all the member clusters. You can’t change the ConfigMap’s name. - Creates the service accounts and Roles required for running database workloads in the member clusters.
Run the kubectl mongodb
plugin:
Optional: Set the Istio injection webhook in each member cluster.¶
If you’re using Istio, 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.
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.
Deploy the MongoDB Enterprise Kubernetes Operator in the central cluster.¶
Deploy the MongoDB Enterprise Kubernetes Operator in the central cluster in the mongodb
namespace with Helm or kubectl
.
- Helm
- kubectl
Add the MongoDB Helm Charts for Kubernetes repository to Helm.
Use the MongoDB Helm Charts for Kubernetes to deploy the Kubernetes Operator.
Apply the Kubernetes Operator custom resources.
Download the Kubernetes Operator YAML template.
Optional: Customize the Kubernetes Operator YAML template.
To learn about optional Kubernetes Operator installation settings, see MongoDB Enterprise Kubernetes Operator kubectl and oc Installation Settings.
Apply the Kubernetes Operator YAML file.
Verify that the Kubernetes Operator is deployed.
To verify that the Kubernetes Operator installed correctly, run the following command and verify the output:
- Using kubectl
- Using oc
By default, deployments exist in the
mongodb
namespace. If the following error message appears, ensure you use the correct namespace:To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator and other troubleshooting topics.
Important
If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.
Create a secret to use with Ops Manager and create a ConfigMap.¶
- 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.
- Create a ConfigMap to link the Kubernetes Operator to your Ops Manager project. To learn more, see Create One Project using a ConfigMap.
Deploy Ops Manager on the central cluster and connect to Ops Manager.¶
Review the multi-Kubernetes-cluster deployment exceptions and follow the linked procedures in Deploy an Ops Manager Resource, deploy the Application Database, and Connect to Ops Manager.
Deploy the MongoDBMultiCluster
resource.¶
Set spec.credentials
,
spec.opsManagerconfigMapRef.name
, and
security settings
and deploy the MongoDBMultiCluster
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.
The Kubernetes Operator copies the ConfigMap with the CA that you created in previous steps to each member cluster, generates a concatenated PEM secret, and distributes it to the member clusters.
Verify that the MongoDBMultiCluster
resources are running.¶
For member clusters, run the following commands to verify that the MongoDB Pods are in the running state:
In the central cluster, run the following command to verify that the
MongoDBMultiCluster
resource is in the running state:
Next Steps¶
After deploying your MongoDB replica set across three Kubernetes member clusters, you can add a database user so you can connect to your MongoDB database. See Manage Database Users.