- Deploy Resources >
- Deploy a Sharded Cluster
Deploy a Sharded Cluster¶
On this page
Supported with Cloud Manager and Ops Manager 4.0
You can use Kubernetes Operator to deploy MongoDB instances with Ops Manager version 4.0 or later and Cloud Manager. At any place in this guide that says Ops Manager, you can substitute Cloud Manager.
Sharded clusters provide horizontal scaling for large data sets and enable high throughput operations by distributing the data set across a group of servers.
To learn more about sharding, see Sharding Introduction in the MongoDB manual.
Use this procedure to deploy a new sharded cluster that Ops Manager manages. Later, you can use Ops Manager to add shards and perform other maintenance operations on the cluster.
Prerequisites¶
To deploy a sharded cluster using an object, you need to complete the following procedures:
Considerations¶
Use unique names for the new cluster and its shards.
Important
Replica set, sharded cluster, and shard names within the same project must be unique. Failure to have unique names for the deployments will result in broken backup snapshots.
Do Not Deploy Monitoring Agents inside and outside Kubernetes¶
Do not mix MongoDB deployments outside Kubernetes with ones insider Kubernetes in the same Project.
Due to Kubernetes network translation, a Monitoring Agent outside Kubernetes cannot monitor MongoDB instnaces inside Kubernetes. For this reason, k8s and non-k8s deployments in the same Project is not supported. Use separate projects.
Procedure¶
The procedure for deploying a sharded cluster depends on whether you require the deployment to run with TLS enabled for intra-cluster communication and clients connecting to the database:
- Without TLS
- With TLS
Copy the following example sharded cluster Kubernetes object specification.¶
This is a YAML file that you can modify to meet your desired configuration. Change the highlighted settings to match your desired sharded cluster configuration.
Configure the settings highlighted in the preceding step as follows.¶
Key | Type | Description | Example |
---|---|---|---|
metadata.name |
string | Label for this Kubernetes sharded cluster object. See also
|
myproject |
metadata.namespace |
string | Scope of object names. Kubernetes namespace where this MongoDB Kubernetes resource and other objects are created. Using two different namespaces allows you to delete your sharded cluster or all of the resources in the namespace without affecting your Kubernetes Operator. See also
|
mongodb |
spec.shardCount |
integer | Number of shards to deploy. | 2 |
spec.mongodsPerShardCount |
integer | Number of shard members per shard. | 3 |
spec.mongosCount |
integer | Number of shard routers to deploy. | 2 |
spec.configServerCount |
integer | Number of members of the config server replica set. | 3 |
spec.version |
string | Version of MongoDB that this sharded cluster should run. The format should be To learn more about MongoDB versioning, see MongoDB Versioning in the MongoDB Manual. |
3.6.7 |
spec.project |
string | Name of the ConfigMap with the Ops Manager connection configuration. Value must match namespace and name of ConfigMap This value must match the value you provided for
If this MongoDB Kubernetes resource is in a different namespace than the
project ConfigMap, you should
set this value to the namespace and name of the
ConfigMap in this format:
Operator manages changes to the ConfigMap The Kubernetes Operator tracks any changes to the ConfigMap and reconciles the state of the MongoDB Kubernetes resource. |
<myproject> or
<namespace>/<myconfigmap> |
spec.credentials |
string | Name of the Kubernetes secret you created as Ops Manager API authentication credentials for the Kubernetes Operator to communicate with Ops Manager. Value must use namespace and name of Secret This value must match the value you provided for
If this object is in a different namespace than the
Secret, you should set this value to the namespace and
name of the Secret in this format:
Operator manages changes to the Secret The Kubernetes Operator tracks any changes to the Secret and reconciles the state of the MongoDB Kubernetes resource. |
<mycredentials> or
<namespace>/<mycredentials> |
spec.type |
string | Type of MongoDB Kubernetes resource to create. | ShardedCluster |
spec.persistent |
string | Optional. Flag indicating if this MongoDB Kubernetes resource should use Persistent Volumes for storage. Persistent volumes are not deleted when the MongoDB Kubernetes resource is stopped or restarted. If this value is To change your Persistent Volume Claims configuration, configure the following collections to meet your deployment requirements:
Warning Your containers must have permissions to write to your Persistent Volume.
The Kubernetes Operator sets Note If you do not use Persistent Volumes, the Disk Usage and Disk IOPS charts cannot be displayed in either the Processes tab on the Deployment page or in the Metrics page when reviewing the data for this deployment. |
true |
Add any additional accepted settings for a sharded cluster deployment.¶
You can also add any of the following optional settings to the object specification file for a sharded cluster deployment:
For config server
spec.configSrvPodSpec.cpu
spec.configSrvPodSpec.cpuRequests
spec.configSrvPodSpec.memory
spec.configSrvPodSpec.memoryRequests
spec.configSrvPodSpec.persistence.single
spec.configSrvPodSpec.persistence.multiple.data
spec.configSrvPodSpec.persistence.multiple.journal
spec.configSrvPodSpec.persistence.multiple.logs
spec.configSrvPodSpec.nodeAffinity
spec.configSrvPodSpec.podAffinity
spec.configSrvPodSpec.podAntiAffinityTopologyKey
For shard routers
spec.mongosPodSpec.cpu
spec.mongosPodSpec.cpuRequests
spec.mongosPodSpec.memory
spec.mongosPodSpec.memoryRequests
spec.mongosPodSpec.nodeAffinity
spec.mongosPodSpec.podAffinity
spec.mongosPodSpec.podAntiAffinityTopologyKey
For shard members
spec.shardPodSpec.cpu
spec.shardPodSpec.cpuRequests
spec.shardPodSpec.memory
spec.shardPodSpec.memoryRequests
spec.shardPodSpec.nodeAffinity
spec.shardPodSpec.persistence.single
spec.shardPodSpec.persistence.multiple.data
spec.shardPodSpec.persistence.multiple.journal
spec.shardPodSpec.persistence.multiple.logs
spec.shardPodSpec.podAffinity
spec.shardPodSpec.podAntiAffinityTopologyKey
Save this file with a .yaml
file extension.¶
Start your sharded cluster deployment.¶
Invoke the following Kubernetes command to create your sharded cluster:
Check the log after running this command. If the creation was successful, you should see a message similar to the following:
Track the status of your sharded cluster deployment.¶
To check the status of your MongoDB Kubernetes resource, invoke the following command:
The -w
flag means “watch”. With the “watch” flag set, the output
refreshes immediately when something changes until the status phase
achieves the Running
state.
If the deployment fails, see Troubleshooting the Kubernetes Operator.
The MongoDB Enterprise Kubernetes Operator can use TLS certificates to encrypt communication between:
- MongoDB hosts in a replica set or sharded cluster configuration
- Clients (
mongo
shell, drivers, MongoDB Compass, and others) and the MongoDB deployment
The following procedure walks you through deploying a replica set with TLS enabled:
Copy the following example sharded cluster Kubernetes object specification.¶
This is a YAML file that you can modify to meet your desired configuration. Change the highlighted settings to match your desired sharded cluster configuration.
Configure the settings highlighted in the preceeding step as follows.¶
Key | Type | Description | Example |
---|---|---|---|
metadata.name |
string | Label for this Kubernetes sharded cluster object. See also
|
myproject |
metadata.namespace |
string | Scope of object names. Kubernetes namespace where this MongoDB Kubernetes resource and other objects are created. Using two different namespaces allows you to delete your sharded cluster or all of the resources in the namespace without affecting your Kubernetes Operator. See also
|
mongodb |
spec.shardCount |
integer | Number of shards to deploy. | 2 |
spec.mongodsPerShardCount |
integer | Number of shard members per shard. | 3 |
spec.mongosCount |
integer | Number of shard routers to deploy. | 2 |
spec.configServerCount |
integer | Number of members of the config server replica set. | 3 |
spec.version |
string | Version of MongoDB that this sharded cluster should run. The format should be To learn more about MongoDB versioning, see MongoDB Versioning in the MongoDB Manual. |
3.6.7 |
spec.project |
string | Name of the ConfigMap with the Ops Manager connection configuration. Value must match namespace and name of ConfigMap This value must match the value you provided for
If this MongoDB Kubernetes resource is in a different namespace than the
project ConfigMap, you should
set this value to the namespace and name of the
ConfigMap in this format:
Operator manages changes to the ConfigMap The Kubernetes Operator tracks any changes to the ConfigMap and reconciles the state of the MongoDB Kubernetes resource. |
<myproject> or
<namespace>/<myconfigmap> |
spec.credentials |
string | Name of the Kubernetes secret you created as Ops Manager API authentication credentials for the Kubernetes Operator to communicate with Ops Manager. Value must use namespace and name of Secret This value must match the value you provided for
If this object is in a different namespace than the
Secret, you should set this value to the namespace and
name of the Secret in this format:
Operator manages changes to the Secret The Kubernetes Operator tracks any changes to the Secret and reconciles the state of the MongoDB Kubernetes resource. |
<mycredentials> or
<namespace>/<mycredentials> |
spec.type |
string | Type of MongoDB Kubernetes resource to create. | ShardedCluster |
spec.persistent |
string | Optional. Flag indicating if this MongoDB Kubernetes resource should use Persistent Volumes for storage. Persistent volumes are not deleted when the MongoDB Kubernetes resource is stopped or restarted. If this value is To change your Persistent Volume Claims configuration, configure the following collections to meet your deployment requirements:
Warning Your containers must have permissions to write to your Persistent Volume.
The Kubernetes Operator sets Note If you do not use Persistent Volumes, the Disk Usage and Disk IOPS charts cannot be displayed in either the Processes tab on the Deployment page or in the Metrics page when reviewing the data for this deployment. |
true |
If you wish to enable TLS on your sharded cluster, add the TLS settings to the ConfigMap.¶
Enable TLS in your deployment by configuring the following settings in your Kubernetes object:
Key | Type | Description | Example |
---|---|---|---|
spec.security.tls.enabled |
boolean | If this value is The default |
true |
spec.security.clusterAuthenticationMode |
string | Optional. Enables X.509 internal cluster authentication. Remove this field from your ConfigMap to disable X.509 internal cluster authentication. Important Once internal cluster authentication is enabled, it can not be disabled. |
x509 |
spec.additionalMongodConfig.net.ssl.mode |
string | Optional. Changes the TLS mode
the MongoDB deployment uses for intra-cluster communication and
clients connecting to the database. |
requireSSL |
The following options are valid for
spec.additionalMongodConfig.net.ssl.mode
:
Value | Description |
---|---|
allowSSL |
Connections between servers do not use TLS. For incoming connections, the server accepts both TLS and non-TLS. |
preferSSL |
Connections between servers use TLS. For incoming connections, the server accepts both TLS and non-TLS. |
requireSSL |
The server uses and accepts only TLS encrypted connections. |
Note
MongoDB custom resources do not support all
mongod
command line options. If you use an
unsupported option in your object specification file, the backing
MongoDB Agent
overrides the unsupported options. For a complete list of options
supported by MongoDB custom resources, see MongoDB Kubernetes Object Specification.
Add any additional accepted settings for a sharded cluster deployment.¶
You can also add any of the following optional settings to the object specification file for a sharded cluster deployment:
For config server
spec.configSrvPodSpec.cpu
spec.configSrvPodSpec.cpuRequests
spec.configSrvPodSpec.memory
spec.configSrvPodSpec.memoryRequests
spec.configSrvPodSpec.persistence.single
spec.configSrvPodSpec.persistence.multiple.data
spec.configSrvPodSpec.persistence.multiple.journal
spec.configSrvPodSpec.persistence.multiple.logs
spec.configSrvPodSpec.nodeAffinity
spec.configSrvPodSpec.podAffinity
spec.configSrvPodSpec.podAntiAffinityTopologyKey
For shard routers
spec.mongosPodSpec.cpu
spec.mongosPodSpec.cpuRequests
spec.mongosPodSpec.memory
spec.mongosPodSpec.memoryRequests
spec.mongosPodSpec.nodeAffinity
spec.mongosPodSpec.podAffinity
spec.mongosPodSpec.podAntiAffinityTopologyKey
For shard members
spec.shardPodSpec.cpu
spec.shardPodSpec.cpuRequests
spec.shardPodSpec.memory
spec.shardPodSpec.memoryRequests
spec.shardPodSpec.nodeAffinity
spec.shardPodSpec.persistence.single
spec.shardPodSpec.persistence.multiple.data
spec.shardPodSpec.persistence.multiple.journal
spec.shardPodSpec.persistence.multiple.logs
spec.shardPodSpec.podAffinity
spec.shardPodSpec.podAntiAffinityTopologyKey
Save this file with a .yaml
file extension.¶
Start your sharded cluster deployment.¶
Invoke the following Kubernetes command to create your sharded cluster:
Check the status of your deployment.¶
The Kubernetes Operator will proceed to create the MongoDB resources and request the Kubernetes Certificate Authority to approve the database host’s certificates. Verify that the certificates are pending approval by running the following command:
The status
field of the output should resemble the following:
If you do not see the status.message
above, see
Troubleshooting the Kubernetes Operator to help diagnose the issue.
Approve the certificate for each host in your deployment.¶
Retrieve the CSRs for each host by running the following command:
The output of the command and number of certificates to approve
depend on whether X.509 internal cluster authentication is enabled by
setting spec.security.clusterAuthenticationMode
to
x509
in step 4.
- X.509 Disabled
- X.509 Enabled
The command’s output resembles the following:
Using the NAME
field above, approve each certificate from the
previous command’s output using the following command:
Example
The following commands approve the certificates for the replica set example in the previous step:
kubectl
prints a message to the console when a certificate
is approved.
The command’s output resembles the following:
Using the NAME
field above, approve each certificate from the
previous command’s output using the following command:
Example
The following commands approve the certificates for the replica set example in the previous step:
kubectl
prints a message to the console when a certificate
is approved.
When spec.security.clusterAuthenticationMode
is set to
x509
an additional CSR will be generated per host for the
clusterfile.
After the first batch of certificates are approved, run the command to retrieve the CSRs again:
The clusterfile CSRs are now present in the output:
Approve the clusterfile CSRs using the same command:
Example
The following commands approve the clusterfile certificates:
Track the status of your sharded cluster deployment.¶
To check the status of your MongoDB Kubernetes resource, invoke the following command:
The -w
flag means “watch”. With the “watch” flag set, the output
refreshes immediately when something changes until the status phase
achieves the Running
state.
If the deployment fails, see Troubleshooting the Kubernetes Operator.