Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Managing Yandex StoreDoc shards

Written by
Updated at February 6, 2026

You can create a sharded cluster or you can enable sharding later. Next, you can add and configure shards.

To ensure high availability, each shard must consist of at least three MONGOD hosts. We do not recommend sharding small collections, as a standard replica set will process queries faster.

Alert

Once cluster sharding is enabled:

  • You cannot turn sharding off. The cluster will always maintain a minimum of MONGOS, MONGOCFG, or MONGOINFRA hosts, depending on the sharding type.
  • All database access must go through MONGOS or MONGOINFRA hosts, which route queries to the shards. Update the host addresses in your application code accordingly.

Enabling sharding

Using the Yandex StoreDoc interface, you can quickly set up a Yandex StoreDoc sharding infrastructure.

For details on how to shard your Yandex StoreDoc database and collections directly, see Sharding collections.

To enable sharding, you need:

  • At least three MONGOINFRA hosts for standard sharding.
  • At least two MONGOS and three MONGOCFG hosts for advanced sharding.

Note

The b1.medium and b2.medium host classes do not support sharding. If you do not see the Shards tab, upgrade your cluster’s host class to the supported level.

  1. Open the folder dashboard.

  2. Navigate to the Yandex StoreDoc service.

  3. Click the name of your cluster and select the Shards tab.

  4. Click Enable.

  5. Select sharding type:

    • Standard: Based on MONGOINFRA hosts.

    • Advanced: Based on MONGOS and MONGOCFG hosts.

      For more information, see Sharding.

    Warning

    Once you enable sharding, you cannot change its type.

  6. Configure the settings of the hosts that will provide access to the sharded data.

  7. Click Enable sharding.

The cluster will begin updating. During this process, the system will create the requested hosts and the cluster’s first shard.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

  • To enable standard cluster sharding using MONGOINFRA hosts, run the command below. Note that this example does not show all available command options:

    yc managed-mongodb cluster enable-sharding \
  --cluster-name=<cluster_name> \
  --host type=mongoinfra,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --host type=mongoinfra,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --host type=mongoinfra,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --mongoinfra resource-preset=<host_class>,`
    `disk-size=<storage_size_in_GB>,`
    `disk-type=<disk_type>

    Where:

  • To enable advanced cluster sharding using MONGOS and MONGOCFG hosts, run the command below. Note that this example does not show all available command options.

    yc managed-mongodb cluster enable-sharding \
  --cluster-name=<cluster_name> \
  --host type=mongos,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --host type=mongos,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --mongos resource-preset=<host_class>,`
    `disk-size=<storage_size_in_GB>,`
    `disk-type=<disk_type> \
  --host type=mongocfg,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --host type=mongocfg,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --host type=mongocfg,`
    `zone-id=<availability_zone>,`
    `subnet-name=<subnet_name> \
  --mongocfg resource-preset=<host_class>,`
    `disk-size=<storage_size_in_GB>,`
    `disk-type=<disk_type>

    Where:

  1. Make sure the provider version you are using is 0.90 or higher:

    terraform version

    Result example:

    Terraform v1.4.6
on darwin_arm64
+ provider registry.terraform.io/yandex-cloud/yandex v0.91.0
    If the version is older

    Update the provider version:

    1. In the folder with the .tf configuration file, add the credentials to environment variables.

    2. In the same folder, initialize the provider with the updated version specified in the configuration file:

      terraform init -upgrade

    3. Check the provider version:

      terraform version

  2. Open the current Terraform configuration file describing your infrastructure.

    To learn how to create this file, see Creating a cluster.

  3. Add new resources to the configuration file.

    For standard cluster sharding using MONGOINFRA hosts
    resources_mongoinfra {
  resource_preset_id = "<host_class>"
  disk_type_id       = "<disk_type>"
  disk_size          = <storage_size_in_GB>
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongoinfra"
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongoinfra"
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongoinfra"
}
    For advanced cluster sharding using MONGOS and MONGOCFG hosts
    resources_mongos {
  resource_preset_id = "<host_class>"
  disk_type_id       = "<disk_type>"
  disk_size          = <storage_size_in_GB>
}

resources_mongocfg {
  resource_preset_id = "<host_class>"
  disk_type_id       = "<disk_type>"
  disk_size          = <storage_size_in_GB>
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongos"
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongos"
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongocfg"
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongocfg"
}

host {
  zone_id   = "<availability_zone>"
  subnet_id = "<subnet_ID>"
  type      = "mongocfg"
}

  4. Validate your configuration.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate

      Terraform will show any errors found in your configuration files.

  5. Confirm resource changes.

    1. Run this command to view the planned changes:

      terraform plan

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see this Terraform provider guide.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.EnableSharding method, e.g., via the following cURL request:

    curl \
    --request POST \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>:enableSharding' \
    --data '{
              "<Yandex_StoreDoc_host_type>": {
                "resources": {
                  "resourcePresetId": "<host_class>",
                  "diskSize": "<storage_size_in_bytes>",
                  "diskTypeId": "<disk_type>"
                }
              },
              "hostSpecs": [
                {
                  "zoneId": "<availability_zone>",
                  "subnetId": "<subnet_ID>",
                  "assignPublicIp": <allow_public_access_to_host>,
                  "type": "<host_type>",
                  "shardName": "<shard_name>",
                  "hidden": <hide_host>,
                  "secondaryDelaySecs": "<lag_in_seconds>",
                  "priority": "<host_priority_for_assignment_as_master>",
                  "tags": "<host_labels>"
                },
                { <similar_settings_for_host_2> },
                { ... },
                { <similar_configuration_for_host_N> }
              ]
            }'

    Where:

    • Yandex StoreDoc host type depends on the sharding type. The possible values are mongocfg, mongos, and mongoinfra.

    • hostSpecs is an array of new hosts, in which each element contains the settings for a single host. The number of hosts depends on the sharding type.

      • zoneId: Availability zone.
      • subnetId: Subnet ID.
      • assignPublicIp: Controls whether the host is accessible via a public IP address, true or false.
      • type: Host type, MONGOINFRA, MONGOS, or MONGOCFG.
      • shardName: Shard name.
      • hidden: Determines whether the host is hidden, true or false.
      • secondaryDelaySecs: Host’s replication lag behind the master.
      • priority: Host priority for master promotion during failover.
      • tags: Host tags.

    You can get the cluster ID from the list of clusters in your folder.

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.EnableSharding method, e.g., via the following gRPCurl request:

    grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/mongodb/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
          "cluster_id": "<cluster_ID>",
          "<Yandex_StoreDoc_host_type>": {
            "resources": {
              "resource_preset_id": "<host_class>",
              "disk_size": "<storage_size_in_bytes>",
              "disk_type_id": "<disk_type>"
            }
          },
          "host_specs": [
            {
              "zone_id": "<availability_zone>",
              "subnet_id": "<subnet_ID>",
              "assign_public_ip": <allow_public_access_to_host>,
              "type": "<host_type>",
              "shard_name": "<shard_name>",
              "hidden": <hide_host>,
              "secondary_delay_secs": "<lag_in_seconds>",
              "priority": "<host_priority_for_assignment_as_master>",
              "tags": "<host_labels>"
            },
            { <similar_settings_for_host_2> },
            { ... },
            { <similar_configuration_for_host_N> }
          ]
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.mongodb.v1.ClusterService.EnableSharding

    Where:

    • Yandex StoreDoc host type depends on the sharding type. The possible values are mongocfg, mongos, and mongoinfra.

    • host_specs is an array of new hosts, in which each element contains the settings for a single host. The number of hosts depends on the sharding type.

      • zone_id: Availability zone.
      • subnet_id: Subnet ID.
      • assign_public_ip: Controls whether the host is accessible via a public IP address, true or false.
      • type: Host type, MONGOINFRA, MONGOS, or MONGOCFG.
      • shard_name: Shard name.
      • hidden: Determines whether the host is hidden, true or false.
      • secondary_delay_secs: Host’s replication lag behind the master.
      • priority: Host priority for master promotion during failover.
      • tags: Host tags.

    You can get the cluster ID from the list of clusters in your folder.

  4. Check the server response to make sure your request was successful.

Getting a list of cluster shards

  1. Open the folder dashboard.
  2. Navigate to the Yandex StoreDoc service.
  3. Click the name of your cluster and select the Shards tab.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To get a list of cluster shards, run this command:

yc managed-mongodb shards list --cluster-name <cluster_name>

Result:

+------+
| NAME |
+------+
| rs01 |
| rs02 |
+------+

You can get the cluster name from the list of clusters in your folder.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.ListShards method, e.g., via the following cURL request:

    curl \
    --request GET \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>/shards'

    You can get the cluster ID from the list of clusters in your folder.

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.ListShards method, e.g., via the following gRPCurl request:

    grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/mongodb/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
          "cluster_id": "<cluster_ID>"
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.mongodb.v1.ClusterService.ListShards

    You can get the cluster ID from the list of clusters in your folder.

  4. Check the server response to make sure your request was successful.

Creating a shard

The number of shards in Yandex StoreDoc clusters is limited by the CPU and RAM quotas available to database clusters in your cloud. To review current resource usage, open the Quotas page and find the Yandex StoreDoc section.

  1. Open the folder dashboard.
  2. Navigate to the Yandex StoreDoc service.
  3. Click the name of your cluster and select the Shards tab.
  4. Click Create shard.
  5. Specify the shard name and add the required number of hosts.
  6. Click Create shard.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To create a shard, run the command below. Note that this example does not show all available command options.

yc managed-mongodb shards add <new_shard_name> \
  --cluster-name=<cluster_name> \
  --host zone-id=<availability_zone>,`
    `subnet-name=<subnet_name>

Where:

  1. Make sure the provider version you are using is 0.90 or higher:

    terraform version

    Result example:

    Terraform v1.4.6
on darwin_arm64
+ provider registry.terraform.io/yandex-cloud/yandex v0.91.0
    If the version is older

    Update the provider version:

    1. In the folder with the .tf configuration file, add the credentials to environment variables.

    2. In the same folder, initialize the provider with the updated version specified in the configuration file:

      terraform init -upgrade

    3. Check the provider version:

      terraform version

  2. Open the current Terraform configuration file describing your infrastructure.

    To learn how to create this file, see Creating a cluster.

  3. Add the required number of host blocks to the Yandex StoreDoc cluster description, with the type argument set to MONGOD and the shard_name argument set to the shard name:

    resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
  ...
  host {
    zone_id    = "<availability_zone>"
    subnet_id  = "<subnet_ID>"
    type       = "mongod"
    shard_name = "<shard_name>"
  }
}

  4. Validate your configuration.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate

      Terraform will show any errors found in your configuration files.

  5. Confirm resource changes.

    1. Run this command to view the planned changes:

      terraform plan

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see this Terraform provider guide.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.AddShard method, e.g., via the following cURL request:

    curl \
    --request POST \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>/shards' \
    --data '{
              "shardName": "<shard_name>",
              "hostSpecs": [
                {
                  "zoneId": "<availability_zone>",
                  "subnetId": "<subnet_ID>",
                  "assignPublicIp": <allow_public_access_to_host>,
                  "type": "<host_type>",
                  "shardName": "<shard_name>",
                  "hidden": <hide_host>,
                  "secondaryDelaySecs": "<time_in_seconds>",
                  "priority": "<host_priority_for_assignment_as_master>",
                  "tags": "<labels>"
                },
                { <similar_settings_for_host_2> },
                { ... },
                { <similar_configuration_for_host_N> }
              ]
            }'

    Where:

    • shardName: New shard’s name.

    • hostSpecs: Host settings:

      • zoneId: Availability zone.
      • subnetId: Subnet ID.
      • assignPublicIp: Controls whether the host is accessible via a public IP address, true or false.
      • type: Host type. Specify MONGOD.
      • shardName: Shard name.
      • hidden: Determines whether the host is hidden, true or false.
      • secondaryDelaySecs: Host’s replication lag behind the master.
      • priority: Host priority for master promotion during failover.
      • tags: Host tags.

    You can get the cluster ID from the list of clusters in your folder.

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.AddShard method, e.g., via the following gRPCurl request:

    grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/mongodb/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
          "cluster_id": "<cluster_ID>",
          "shard_name": "<shard_name>",
          "host_specs": [
            {
              "zone_id": "<availability_zone>",
              "subnet_id": "<subnet_ID>",
              "assign_public_ip": <allow_public_access_to_host>,
              "type": "<host_type>",
              "shard_name": "<shard_name>",
              "hidden": <hide_host>,
              "secondary_delay_secs": "<time_in_seconds>",
              "priority": "<host_priority_for_assignment_as_master>",
              "tags": "<labels>"
            },
            { <similar_settings_for_host_2> },
            { ... },
            { <similar_configuration_for_host_N> }
          ]
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.redis.v1.ClusterService.AddShard

    Where:

    • shard_name: New shard’s name.

    • host_specs: Host settings:

      • zone_id: Availability zone.
      • subnet_id: Subnet ID.
      • assign_public_ip: Controls whether the host is accessible via a public IP address, true or false.
      • type: Host type. Specify MONGOD.
      • shard_name: Shard name.
      • hidden: Determines whether the host is hidden, true or false.
      • secondary_delay_secs: Host’s replication lag behind the master.
      • priority: Host priority for master promotion during failover.
      • tags: Host tags.

    You can get the cluster ID from the list of clusters in your folder.

  4. Check the server response to make sure your request was successful.

Deleting a shard

You can delete a shard from a Yandex StoreDoc cluster, provided it is not the only shard. To replace the only shard, first create a new shard and then delete the old one.

Note

The system will invoke the removeShard operation for the shard slated for removal. This operation will safely migrate its data to the remaining shards.

  1. Open the folder dashboard.
  2. Navigate to the Yandex StoreDoc service.
  3. Click the name of your cluster and select the Shards tab.
  4. Find the shard you need in the list, click in its row, and select Delete.
  5. In the window that opens, click Remove.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

To delete a shard from a cluster, run this command:

yc managed-mongodb shards delete <shard_name> \
  --cluster-name=<cluster_name>

You can get the shard name from the list of cluster shards, and the cluster name from the list of clusters in your folder.

  1. Open the current Terraform configuration file describing your infrastructure.

    To learn how to create this file, see Creating a cluster.

  2. Delete all shard-related host blocks from the Yandex StoreDoc cluster description.

  3. Validate your configuration.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate

      Terraform will show any errors found in your configuration files.

  4. Type yes and press Enter.

    1. Run this command to view the planned changes:

      terraform plan

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see this Terraform provider guide.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.DeleteShard method, e.g., via the following cURL request:

    curl \
    --request DELETE \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>/shards/<shard_name>'

    You can get the cluster ID from the list of clusters in your folder, and the shard name from the list of cluster shards.

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and place it in an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.DeleteShard method, e.g., via the following gRPCurl request:

    grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/mdb/mongodb/v1/cluster_service.proto \
    -rpc-header "Authorization: Bearer $IAM_TOKEN" \
    -d '{
          "cluster_id": "<cluster_ID>",
          "shard_name": "<shard_name>" 
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.mongodb.v1.ClusterService.DeleteShard

    You can get the cluster ID from the list of clusters in your folder, and the shard name from the list of cluster shards.

  4. Check the server response to make sure your request was successful.

Previous
Managing database users
Next
Primary replica failover