Navigation

Deploy a Sharded Cluster

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 the Sharding Introduction in the MongoDB manual.

To deploy a new sharded cluster that Atlas can manage, use the Atlas Open Service Broker and Kubernetes. After deployment, use Atlas to add shards and perform other maintenance operations on the cluster.

Prerequisites

You create Atlas sharded clusters by defining an object. To deploy a sharded cluster using an Kubernetes object, you must first install the Atlas Open Service Broker.

Considerations

Limits of the Atlas API

Atlas Open Service Broker uses the Create a Cluster endpoint of the Atlas API to deploy sharded clusters. Any requirements or limitations of that API also apply to the Atlas Open Service Broker.

Procedure

1

Create a ServiceInstance resource definition for your sharded cluster.

  1. Copy one of the following resource definition examples based on the scope of your Atlas Open Service Broker instance.

    If you registered the Atlas Open Service Broker instance as:


    Copy the following YAML file, which you can modify to meet your desired configuration:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    apiVersion: servicecatalog.k8s.io/v1beta1
    kind: ServiceInstance
    metadata:
      name: <CLUSTER_NAME>
      namespace: <NAMESPACE>
    spec:
      clusterServiceClassExternalName: <CLOUD_SERVICE_PROVIDER_CLASS>
      clusterServicePlanExternalName: <INSTANCE_SIZE_PLAN>
      parameters:
        cluster:
          numShards: <NUMBER_OF_SHARDS>
          providerSettings:
            regionName: <ATLAS_REGION>
    

    Copy the following YAML file, which you can modify to meet your desired configuration:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    apiVersion: servicecatalog.k8s.io/v1beta1
    kind: ServiceInstance
    metadata:
      name: <CLUSTER_NAME>
      namespace: <NAMESPACE>
    spec:
      serviceClassExternalName: <CLOUD_SERVICE_PROVIDER_CLASS>
      servicePlanExternalName: <INSTANCE_SIZE_PLAN>
      parameters:
        cluster:
          numShards: <NUMBER_OF_SHARDS>
          providerSettings:
            regionName: <ATLAS_REGION>
    
  2. Open your preferred text editor and paste the resource definition into a new text file.

2

Configure the required settings.

To deploy a sharded cluster, you must specify the following settings:

Key Description Example
metadata.name Name of the cluster in Kubernetes. Atlas randomly generates a corresponding Atlas cluster name. my-atlas-cluster
metadata.namespace Kubernetes namespace where this cluster is created. atlas
spec.clusterServiceClassExternalName

Kubernetes class which corresponds to your Atlas cloud service provider.

View the available classes by invoking the following command:

svcat marketplace

Class names are listed in the CLASS column of the command output.

mongodb-atlas-aws
spec.clusterServicePlanExternalName

Kubernetes service plan which corresponds to the desired Atlas instance size.

View the available plans by invoking the following command:

svcat marketplace

Plan names are listed in the PLANS column of the command output.

M10
spec.parameters.cluster
.numShards
Number of shards in the sharded cluster. 3
spec.parameters.cluster
.providerSettings.regionName

Atlas region where the cluster is created.

Important

Make sure you use the Atlas region name for the desired region, not the cloud provider region name.

For a list of available regions, see the Atlas documentation for your cloud service provider:

EU_CENTRAL_1
Key Description Example
metadata.name Name of the cluster in Kubernetes. Atlas randomly generates a corresponding Atlas cluster name. my-atlas-cluster
metadata.namespace Kubernetes namespace where this cluster is created. atlas
spec.serviceClassExternalName

Kubernetes class which corresponds to your Atlas cloud service provider.

View the available classes by invoking the following command:

svcat marketplace

Class names are listed in the CLASS column of the command output.

mongodb-atlas-aws
spec.servicePlanExternalName

Kubernetes service plan which corresponds to the desired Atlas instance size.

View the available plans by invoking the following command:

svcat marketplace

Plan names are listed in the PLANS column of the command output.

M10
spec.parameters.cluster
.numShards
Number of shards in the sharded cluster. 3
spec.parameters.cluster
.providerSettings.regionName

Atlas region where the cluster is created.

Important

Make sure you use the Atlas region name for the desired region, not the cloud provider region name.

For a list of available regions, see the Atlas documentation for your cloud service provider:

EU_CENTRAL_1
3

(Optional) Configure any additional settings for a sharded cluster deployment.

You can specify additional cluster settings under the spec.parameters.cluster key. These settings correspond to the request body parameters of the Create a Cluster API method.

Important

The following API parameters are overwritten by the required Atlas Open Service Broker settings from the previous step and should not be specified:

  • providerSettings.instanceSizeName
  • providerSettings.providerName
  • name

Example

This example resource definition creates a sharded cluster called my-sharded-cluster in the atlas namespace that has the following configuration:

  • Managed by a cluster-scoped (ClusterServiceBroker) Atlas Open Service Broker
  • AWS as a cloud service provider
  • An instance size of M10
  • Composed of three shards
  • Located in the EU (Frankfurt) region
  • Auto-scaling disabled
  • Atlas continuous backups enabled
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceInstance
metadata:
  name: my-sharded-cluster
  namespace: atlas
spec:
  clusterServiceClassExternalName: mongodb-atlas-aws
  clusterServicePlanExternalName: M10
  parameters:
    cluster:
      numShards: 3
      providerSettings:
        regionName: EU_CENTRAL_1
      autoscaling:
        diskGBEnabled: false
      backupEnabled: true

Example

This example resource definition creates a sharded cluster called my-sharded-cluster in the atlas namespace that has the following configuration:

  • Managed by a namespace-scoped (ServiceBroker) Atlas Open Service Broker
  • AWS as a cloud service provider
  • An instance size of M10
  • Composed of three shards
  • Located in the EU (Frankfurt) region
  • Auto-scaling disabled
  • Atlas continuous backups enabled
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceInstance
metadata:
  name: my-sharded-cluster
  namespace: atlas
spec:
  serviceClassExternalName: mongodb-atlas-aws
  servicePlanExternalName: M10
  parameters:
    cluster:
      numShards: 3
      providerSettings:
        regionName: EU_CENTRAL_1
      autoscaling:
        diskGBEnabled: false
      backupEnabled: true
4

Save the file as sharded-cluster.yaml.

5

Deploy the sharded cluster.

Invoke the following Kubernetes command to create your sharded cluster:

kubectl apply -f sharded-cluster.yaml
6

Track the status of your sharded cluster deployment.

To view the status of your deployment, pass the metadata.name from sharded-cluster.yaml into the following command:

svcat describe instance <METADATA.NAME> -n <NAMESPACE>

As the sharded cluster is being deployed, the command returns the following status:

Provisioning - The instance is being provisioned asynchronously

Once the sharded cluster deploys successfully, the command returns the following status:

Ready - The instance was provisioned successfully