Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
    • Yandex Cloud Partner program
  • Blog
  • Pricing
  • Documentation
© 2025 Direct Cursus Technology L.L.C.
Yandex Managed Service for MongoDB
  • Getting started
    • All guides
      • Information about existing clusters
      • Creating a cluster
      • Updating cluster settings
      • MongoDB version upgrade
      • Stopping and starting a cluster
      • Managing cluster hosts
      • Migrating hosts to a different availability zone
      • Managing backups
      • Deleting a cluster
  • Access management
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Public materials
  • Release notes

In this article:

  • Creating a cluster
  • Creating a cluster copy
  • Examples
  • Creating a single-host cluster
  • Creating sharded clusters
  1. Step-by-step guides
  2. Clusters
  3. Creating a cluster

Creating a MongoDB cluster

Written by
Yandex Cloud
Updated at May 5, 2025
  • Creating a cluster
  • Creating a cluster copy
  • Examples
    • Creating a single-host cluster
    • Creating sharded clusters

A MongoDB cluster is one or more database hosts between which you can configure replication. Replication is enabled by default in any cluster consisting of more than one host, where the primary host accepts write requests and asynchronously replicates the changes in the secondary hosts.

Note

  • The number of hosts you can create together with a MongoDB cluster depends on the selected disk type and host class.
  • Available disk types depend on the selected host class.

Creating a clusterCreating a cluster

To create a Managed Service for MongoDB cluster, you will need the vpc.user and managed-mongodb.editor roles or higher. For information on assigning roles, see the Identity and Access Management documentation.

Management console
CLI
Terraform
REST API
gRPC API

To create a Managed Service for MongoDB cluster:

  1. In the management console, select the folder where you want to create a DB cluster.

  2. Select Managed Service for MongoDB.

  3. Click Create cluster.

  4. Under Basic parameters:

    • Enter a name in the Cluster name field. The cluster name must be unique within the cloud.

    • (Optional) Enter a cluster Description.

    • Select the environment where you want to create the cluster (you cannot change the environment once the cluster is created):

      • PRODUCTION: For stable versions of your apps.
      • PRESTABLE: For testing purposes. The prestable environment is similar to the production environment and likewise covered by the SLA, but it is the first to get new functionalities, improvements, and bug fixes. In the prestable environment, you can test compatibility of new versions with your application.
    • Specify the DBMS version.

  5. Under Host class, select:

    • One of the available platforms.
    • Configuration type: memory-optimized, cpu-optimized, standard, or burstable.
    • Host class: Defines the technical specifications of the VMs where the DB hosts will be deployed. When you change the host class for the cluster, the characteristics of all existing hosts change, too.
  6. Under Size of storage:

    • Select the disk type.

      The selected type determines the increments in which you can change your disk size:

      • Network HDD and SSD storage: In increments of 1 GB.
      • Local SSD storage:
        • For Intel Broadwell and Intel Cascade Lake: In increments of 100 GB.
        • For Intel Ice Lake: In increments of 368 GB.
      • Non-replicated SSDs and ultra high-speed network SSDs with three replicas: In increments of 93 GB.
    • Select the storage size to be used for data and backups. For more information on how backups take up storage space, see Backups.

  7. Under Database, specify the DB attributes:

    • DB name.

      A database name may contain Latin letters, numbers, underscores, and hyphens. The name may be up to 63 characters long. Such names as config, local, admin, and mdb_internal are reserved for Managed Service for MongoDB. You cannot create DBs with these names.

    • Username.

    • User password. The password must be at least 8 characters long.

  8. Under Network settings, select:

    • Cloud network for the cluster.
    • Security groups for the cluster network traffic. You may need to additionally set up security groups to be able to connect to the cluster.
  9. Under Hosts, add the DB hosts created with the cluster:

    • Click Add host.
    • Select an availability zone.
    • Select a subnet in the specified availability zone. If there is no subnet, create one.
    • If the host must be available outside Yandex Cloud, enable Public access.

    To ensure fault tolerance, you need at least 3 hosts for local-ssd and network-ssd-nonreplicated disk types. For more information, see Storage.

    By default, hosts are created in different availability zones. Read more about host management.

  10. Configure additional cluster settings, if required:

    • Backup start time (UTC): Time interval during which the cluster backup starts. Time is specified in 24-hour UTC format. The default time is 22:00 - 23:00 UTC.

    • Retention period for automatic backups, days

      Retention period for automatic backups. If an automatic backup expires, it is deleted. The default is 7 days. This feature is at the Preview stage. For more information, see Backups.

      Changing the retention period affects both new automatic backups and existing backups. For example, if the initial retention period was 7 days, and the remaining lifetime of a separate automatic backup is 1 day, increasing the retention period to 9 days will change the remaining lifetime of this backup to 3 days.

      For an existing cluster, automatic backups are stored for a specified number of days whereas manually created ones are stored indefinitely. After a cluster is deleted, all backups persist for 7 days.

    • Maintenance window: Maintenance window settings:

      • To enable maintenance at any time, select arbitrary (default).
      • To specify the preferred maintenance start time, select by schedule and specify the desired day of the week and UTC hour. For example, you can choose a time when the cluster is least loaded.

      Maintenance operations are carried out both on enabled and disabled clusters. They may include updating the DBMS, applying patches, and so on.

    • Statistics sampling: Enable this option to use the built-in performance diagnostics tool in the cluster. This feature is at the Preview stage.

    • Deletion protection: Cluster protection from accidental deletion.

      Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

  11. Configure the DBMS settings, if required.

    Note

    Some MongoDB settings depend on the selected host class.

  12. Click Create cluster.

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

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To create a Managed Service for MongoDB cluster:

  1. Check whether the folder has any subnets for the cluster hosts:

    yc vpc subnet list
    

    If there are no subnets in the folder, create the required subnets in VPC.

  2. View the description of the CLI command to create a cluster:

    yc managed-mongodb cluster create --help
    
  3. Specify the cluster parameters in the create command (not all parameters are given in the example):

    yc managed-mongodb cluster create \
      --name <cluster_name> \
      --environment=<environment> \
      --network-name <network_name> \
      --host zone-id=<availability_zone>,`
            `subnet-id=<subnet_ID>,`
            `assign-public-ip=<public_access_to_host>,`
            `hidden=<hide_host>,`
            `secondary-delay-secs=<replica_lag_in_seconds>,`
            `priority=<host_priority> \
      --mongod-resource-preset <host_class> \
      --user name=<username>,password=<user_password> \
      --database name=<DB_name> \
      --mongod-disk-type <network-hdd|network-ssd|network-ssd-nonreplicated|local-ssd> \
      --mongod-disk-size <storage_size_in_GB> \
      --performance-diagnostics=<enable_diagnostics> \
      --deletion-protection
    

    You need to specify the subnet-id if the selected availability zone has two or more subnets.

    Where:

    • --environment: Environment, prestable or production.

    • --host: Host parameters:

      • zone-id: Availability zone.
      • subnet-id: Subnet ID. Specify if two or more subnets are created in the selected availability zone.
      • assign-public-ip: Internet access to the host via a public IP address, true or false.
      • hidden: Hide host, true or false. If the host is hidden, only direct connections will be able to read from it (for example, to make backups from it without adding load to the cluster).
      • secondary-delay-secs: Replica's lag behind the master in seconds. It can be useful for data recovery in case of invalid operations.
      • priority: Priority for assigning the host as a master.
    • --mongod-disk-type: Disk type.

    • --performance-diagnostics: Enables cluster performance diagnostics, true or false.

    • --deletion-protection: Cluster protection from accidental deletion, true or false.

      Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

    A database name may contain Latin letters, numbers, underscores, and hyphens. The name may be up to 63 characters long. Such names as config, local, admin, and mdb_internal are reserved for Managed Service for MongoDB. You cannot create DBs with these names.

    Note

    When creating a cluster, the anytime maintenance mode is set by default. You can set a specific maintenance period when updating the cluster settings.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the documentation on the Terraform website or mirror website.

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

To create a Managed Service for MongoDB cluster:

  1. In the configuration file, describe the resources you want to create:

    • Database cluster: Description of the cluster and its hosts.

    • Network: Description of the cloud network where a cluster will be located. If you already have a suitable network, you don't have to describe it again.

    • Subnets: Description of the subnets to connect the cluster hosts to. If you already have suitable subnets, you don't have to describe them again.

    Here is an example of the configuration file structure:

    resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
      name                = "<cluster_name>"
      environment         = "<environment>"
      network_id          = "<network_ID>"
      security_group_ids  = [ "<list_of_security_group_IDs>" ]
      deletion_protection = <cluster_deletion_protection>
    
      cluster_config {
        version = "<MongoDB_version>"
      }
    
      resources_mongod {
        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>"
        assign_public_ip = <public_access>
        host_parameters {
          hidden               = <hide_host>
          secondary_delay_secs = <replica_lag_in_seconds>
          priority             = <host_priority>
        }
      }
    }
    
    resource "yandex_mdb_mongodb_database" "<DB_name>" {
      cluster_id = "<cluster_ID>"
      name       = "<DB_name>"
    }
    
    resource "yandex_mdb_mongodb_user" "<username>" {
      cluster_id = <cluster_ID>
      name       = "<username>"
      password   = "<password>"
      permission {
        database_name = "<DB_name>"
        roles         = [ "<list_of_user_roles>" ]
      }
      depends_on = [
        yandex_mdb_mongodb_database.<DB_name>
      ]
    }
    
    resource "yandex_vpc_network" "<network_name>" { name = "<network_name>" }
    
    resource "yandex_vpc_subnet" "<subnet_name>" {
      name           = "<subnet_name>"
      zone           = "<availability_zone>"
      network_id     = "<network_ID>"
      v4_cidr_blocks = ["<range>"]
    }
    

    Where:

    • environment: Environment, PRESTABLE or PRODUCTION.

    • host: Host parameters:

      • zone_id: Availability zone.
      • subnet_id: ID of a subnet in the selected availability zone.
      • assign_public_ip: Public access to the host, true or false.
      • host_parameters: Additional host parameters:
        • hidden: Hide host, true or false. If the host is hidden, only direct connections will be able to read from it (for example, to make backups from it without adding load to the cluster).
        • secondary_delay_secs: Replica's lag behind the master in seconds. It can be useful for data recovery in case of invalid operations.
        • priority: Host priority for assignment as a master.
    • deletion_protection: Cluster protection from accidental deletion, true or false.

      Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

    • version: MongoDB version, 6.0 or 7.0.

    A database name may contain Latin letters, numbers, underscores, and hyphens. The name may be up to 63 characters long. Such names as config, local, admin, and mdb_internal are reserved for Managed Service for MongoDB. You cannot create DBs with these names.

    To set up the maintenance window (for disabled clusters as well), add the maintenance_window block to the cluster description:

    resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
      ...
      maintenance_window {
        type = <maintenance_type>
        day  = <day_of_week>
        hour = <hour>
      }
      ...
    }
    

    Where:

    • type: Maintenance type. The possible values include:
      • anytime: Anytime.
      • weekly: By schedule.
    • day: Day of the week for the weekly type in DDD format, e.g., MON.
    • hour: Hour of the day for the weekly type in the HH format, e.g., 21.

    For more information about the resources you can create with Terraform, see this provider reference.

  2. Make sure the settings are correct.

    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.

  3. Create a cluster.

    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.

    After this, all required resources will be created in the specified folder, and the host FQDNs will be displayed in the terminal. You can check the new resources and their settings using the management console.

    Timeouts

    The Terraform provider sets the following timeouts for Managed Service for MongoDB cluster operations:

    • Creating a cluster, including by restoring one from a backup: 30 minutes.
    • Editing a cluster: 60 minutes.

    Operations exceeding the set timeout are interrupted.

    How do I change these limits?

    Add the timeouts block to the cluster description, for example:

    resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
      ...
      timeouts {
        create = "1h30m" # An hour and a half
        update = "2h"    # Two hours
      }
    }
    
  1. Get an IAM token for API authentication and put it into the environment variable:

    export IAM_TOKEN="<IAM_token>"
    
  2. Create a file named body.json and add the following contents to it:

    {
      "folderId": "<folder_ID>",
      "name": "<cluster_name>",
      "environment": "<environment>",
      "networkId": "<network_ID>",
      "securityGroupIds": [
        "<security_group_1_ID>",
        "<security_group_2_ID>",
        ...
        "<security_group_N_ID>"
      ],
      "deletionProtection": <cluster_deletion_protection:_true_or_false>,
      "maintenanceWindow": {
        "weeklyMaintenanceWindow": {
          "day": "<day_of_week>",
          "hour": "<hour>"
        }
      },
      "configSpec": {
        "version": "<MongoDB_version>",
        "mongodb": {
          "mongod": {
            "resources": {
              "resourcePresetId": "<host_class>",
              "diskSize": "<storage_size_in_bytes>",
              "diskTypeId": "<disk_type>"
            }
          }
        },
        "backupWindowStart":  {
          "hours": "<hours>",
          "minutes": "<minutes>",
          "seconds": "<seconds>",
          "nanos": "<nanoseconds>"
        },  
        "backupRetainPeriodDays": "<backup_retention_in_days>",
        "performanceDiagnostics": {
          "profilingEnabled": <enable_profiler:_true_or_false>
        }
      },
      "databaseSpecs": [
        {
          "name": "<DB_name>"
        },
        { <similar_configuration_for_DB_2> },
        { ... },
        { <similar_configuration_for_DB_N> }
      ],
      "userSpecs": [
        {
          "name": "<username>",
          "password": "<user_password>",
          "permissions": [
            {
              "databaseName": "<DB_name>",
              "roles": [
                "<role_1>", "<role_2>", ..., "<role_N>"
              ]
            }
          ]
        },
        { <similar_configuration_for_user_2> },
        { ... },
        { <similar_configuration_for_user_N> }
      ],
      "hostSpecs": [
        {
          "zoneId": "<availability_zone>",
          "subnetId": "<subnet_ID>",
          "assignPublicIp": <public_access_to_host:_true_or_false>,
          "type": "<host_type>",
          "shardName": "<shard_name>",
          "hidden": <hide_host:_true_or_false>,
          "secondaryDelaySecs": "<replica_lag_in_seconds>",
          "priority": "<host_priority>",
          "tags": "<host_labels>"
        },
        { <similar_configuration_for_host_2> },
        { ... },
        { <similar_configuration_for_host_N> }
      ],
    }
    

    Where:

    • folderId: Folder ID. You can request it with the list of folders in the cloud.

    • name: Cluster name.

    • environment: Cluster environment, PRODUCTION or PRESTABLE.

    • networkId: ID of the network the cluster will be in.

    • securityGroupIds: Security group IDs.

    • deletionProtection: Cluster protection from accidental deletion, true or false.

      Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

    • maintenanceWindow: Maintenance window settings (including for disabled clusters). In maintenanceWindow, provide one of the two parameters:

      • anytime: Maintenance can take place at any time.

      • weeklyMaintenanceWindow: Maintenance takes place once a week at the specified time:

        • day: Day of week, in DDD format.
        • hour: Hour, in HH format. The values range from 1 to 24 hours.
    • configSpec: Cluster settings:

      • version: MongoDB version: 5.0, 6.0, or 7.0.

      • mongod: Host type.

        • resources: Cluster resources:

          • resourcePresetId: Host class.
          • diskSize: Disk size in bytes.
          • diskTypeId: Disk type.
      • backupWindowStart: Backup window settings.

        In this parameter, specify the backup start time:

        • hours: Between 0 and 23 hours.
        • minutes: Between 0 and 59 minutes.
        • seconds: Between 0 and 59 seconds.
        • nanos: Between 0 and 999999999 nanoseconds.
      • backupRetainPeriodDays: Backup retention in days.

      • performanceDiagnostics: Statistics collection settings:

        • profilingEnabled: Enable profiler.
    • databaseSpecs: Database settings as an array of elements, one for each DB. Each element contains the name parameter with the DB name.

      A database name may contain Latin letters, numbers, underscores, and hyphens. The name may be up to 63 characters long. Such names as config, local, admin, and mdb_internal are reserved for Managed Service for MongoDB. You cannot create DBs with these names.

    • userSpecs: User settings as an array of elements, one for each user. Each element has the following structure:

      • name: Username.

      • password: User password.

      • permissions: User permissions settings:

        • databaseName: Name of the database the user gets access to.
        • roles: Array of user roles. Each role is provided as a separate string in the array. For a list of possible values, see Users and roles.

        For each database, add a separate element with permission settings to the permissions array.

    • hostSpecs: Cluster host settings as an array of elements, one for each host. Each element has the following structure:

      • zoneId: Availability zone.
      • subnetId: Subnet ID.
      • assignPublicIp: Internet access to the host via a public IP address.
      • type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG.
      • shardName: Shard name in a sharded cluster.
      • hidden: Hide host, true or false. If the host is hidden, only direct connections will be able to read from it (for example, to make backups from it without adding load to the cluster).
      • secondaryDelaySecs: Replica's lag behind the master in seconds. It can be useful for data recovery in case of invalid operations.
      • priority: Host priority for assignment as a master.
      • tags: Host labels.
  3. Use the Cluster.Create method and send the following request, e.g., via cURL:

    curl \
        --request POST \
        --header "Authorization: Bearer $IAM_TOKEN" \
        --header "Content-Type: application/json" \
        --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters' \
        --data "@body.json"
    
  4. View the server response to make sure the request was successful.

  1. Get an IAM token for API authentication and put it into the 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 the repository contents are stored in the ~/cloudapi/ directory.

  3. Create a file named body.json and add the following contents to it:

    {
      "folder_id": "<folder_ID>",
      "name": "<cluster_name>",
      "environment": "<environment>",
      "network_id": "<network_ID>",
      "security_group_ids": [
        "<security_group_1_ID>",
        "<security_group_2_ID>",
        ...
        "<security_group_N_ID>"
      ],
      "deletion_protection": <cluster_deletion_protection:_true_or_false>,
      "maintenance_window": {
        "weekly_maintenance_window": {
          "day": "<day_of_week>",
          "hour": "<hour>"
        }
      },
      "config_spec": {
        "version": "<MongoDB_version>",
        "mongodb": {
          "mongod": {
            "resources": {
              "resource_preset_id": "<host_class>",
              "disk_size": "<storage_size_in_bytes>",
              "disk_type_id": "<disk_type>"
            }
          }
        },
        "backup_window_start": {
          "hours": "<hours>",
          "minutes": "<minutes>",
          "seconds": "<seconds>",
          "nanos": "<nanoseconds>"
        },
        "backup_retain_period_days": "<backup_retention_in_days>",
        "performance_diagnostics": {
          "profiling_enabled": <enable_profiler:_true_or_false>
        }
      },
      "database_specs": [
        {
          "name": "<DB_name>"
        },
        { <similar_configuration_for_DB_2> },
        { ... },
        { <similar_configuration_for_DB_N> }
      ],
      "user_specs": [
        {
          "name": "<username>",
          "password": "<user_password>",
          "permissions": [
            {
              "database_name": "<DB_name>",
              "roles": [
                "<role_1>", "<role_2>", ..., "<role_N>"
              ]
            }
          ]
        },
        { <similar_configuration_for_user_2> },
        { ... },
        { <similar_configuration_for_user_N> }
      ],
      "host_specs": [
        {
          "zone_id": "<availability_zone>",
          "subnet_id": "<subnet_ID>",
          "assign_public_ip": <public_access_to_host:_true_or_false>,
          "type": "<host_type>",
          "shard_name": "<shard_name>",
          "hidden": <hide_host:_true_or_false>,
          "secondary_delay_secs": "<replica_lag_in_seconds>",
          "priority": "<host_priority>",
          "tags": "<host_labels>"
        },
        { <similar_configuration_for_host_2> },
        { ... },
        { <similar_configuration_for_host_N> }
      ]
    }
    

    Where:

    • folder_id: Folder ID. You can request it with the list of folders in the cloud.

    • name: Cluster name.

    • environment: Cluster environment, PRODUCTION or PRESTABLE.

    • network_id: ID of the network the cluster will be in.

    • security_group_ids: Security group IDs.

    • deletion_protection: Cluster protection from accidental deletion, true or false.

      Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

    • maintenance_window: Maintenance window settings (including for disabled clusters). In maintenance_window, provide one of the two parameters:

      • anytime: Maintenance can take place at any time.

      • weekly_maintenance_window: Maintenance takes place once a week at the specified time:

        • day: Day of week, in DDD format.
        • hour: Hour, in HH format. The values range from 1 to 24 hours.
    • config_spec: Cluster settings:

      • version: MongoDB version: 5.0, 6.0, or 7.0.
        • mongod: Host type.

          • resources: Cluster resources:

            • resource_preset_id: Host class.
            • disk_size: Disk size in bytes.
            • disk_type_id: Disk type.
        • backup_window_start: Backup window settings.

          In this parameter, specify the backup start time:

          • hours: Between 0 and 23 hours.
          • minutes: Between 0 and 59 minutes.
          • seconds: Between 0 and 59 seconds.
          • nanos: Between 0 and 999999999 nanoseconds.
        • backup_retain_period_days: Backup retention in days.

        • performance_diagnostics: Statistics collection settings:

          • profiling_enabled: Enable profiler.
    • database_specs: Database settings as an array of elements, one for each DB. Each element contains the name parameter with the DB name.

      A database name may contain Latin letters, numbers, underscores, and hyphens. The name may be up to 63 characters long. Such names as config, local, admin, and mdb_internal are reserved for Managed Service for MongoDB. You cannot create DBs with these names.

    • user_specs: User settings as an array of elements, one for each user. Each element has the following structure:

      • name: Username.

      • password: User password.

      • permissions: User permission settings:

        • database_name: Name of the database the user gets access to.
        • roles: Array of user roles. Each role is provided as a separate string in the array. For a list of possible values, see Users and roles.

        For each database, add a separate element with permission settings to the permissions array.

    • host_specs: Cluster host settings as an array of elements, one for each host. Each element has the following structure:

      • zone_id: Availability zone.
      • subnet_id: Subnet ID.
      • assign_public_ip: Internet access to the host via a public IP address.
      • type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG.
      • shard_name: Shard name in a sharded cluster.
      • hidden: Hide host, true or false. If the host is hidden, only direct connections will be able to read from it (for example, to make backups from it without adding load to the cluster).
      • secondaryDelaySecs: Replica's lag behind the master in seconds. It can be useful for data recovery in case of invalid operations.
      • priority: Host priority for assignment as a master.
      • tags: Host labels.
  4. Use the ClusterService.Create call and send the following request, e.g., via gRPCurl:

    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 @ \
        mdb.api.cloud.yandex.net:443 \
        yandex.cloud.mdb.mongodb.v1.ClusterService.Create \
        < body.json
    
  5. View the server response to make sure the request was successful.

Warning

If you specified security group IDs when creating a cluster, you may also need to additionally configure security groups to connect to the cluster.

Creating a cluster copyCreating a cluster copy

You can create a MongoDB cluster using the settings of another one created earlier. To do so, you need to import the configuration of the source MongoDB cluster to Terraform. This way you can either create an identical copy or use the imported configuration as the baseline and modify it as needed. Importing a configuration is a good idea when the source MongoDB cluster has a lot of settings and you need to create a similar one.

To create a MongoDB cluster copy:

Terraform
  1. If you do not have Terraform yet, install it.

  2. Get the authentication credentials. You can add them to environment variables or specify them later in the provider configuration file.

  3. Configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it.

  4. Place the configuration file in a separate working directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.

  5. In the same working directory, place a .tf file with the following contents:

    resource "yandex_mdb_mongodb_cluster" "old" { }
    
  6. Write the ID of the initial MongoDB cluster to the environment variable:

    export MONGODB_CLUSTER_ID=<cluster_ID>
    

    You can request the ID with the list of clusters in the folder.

  7. Import the settings of the initial MongoDB cluster into the Terraform configuration:

    terraform import yandex_mdb_mongodb_cluster.old ${MONGODB_CLUSTER_ID}
    
  8. Get the imported configuration:

    terraform show
    
  9. Copy it from the terminal and paste it into the .tf file.

  10. Place the file in the new imported-cluster directory.

  11. Modify the copied configuration so that you can create a new cluster from it:

    • Specify the new cluster name in the resource string and the name parameter.
    • Delete created_at, health, id, sharded, and status.
    • In the host sections, delete health and name.
    • If the maintenance_window section has type = "ANYTIME", delete the hour parameter.
    • Delete all user sections (if any). You can add database users using the separate yandex_mdb_mongodb_user resource.
    • Optionally, make further changes if you need to customize the configuration.
  12. Get the authentication credentials in the imported-cluster directory.

  13. In the same directory, configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it.

  14. Place the configuration file in the imported-cluster directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.

  15. Check that the Terraform configuration files are correct:

    terraform validate
    

    If there are any errors in the configuration files, Terraform will point them out.

  16. Create the required infrastructure:

    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.

    All the required resources will be created in the specified folder. You can check resource availability and their settings in the management console.

Timeouts

The Terraform provider sets the following timeouts for Managed Service for MongoDB cluster operations:

  • Creating a cluster, including by restoring one from a backup: 30 minutes.
  • Editing a cluster: 60 minutes.

Operations exceeding the set timeout are interrupted.

How do I change these limits?

Add the timeouts block to the cluster description, for example:

resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # An hour and a half
    update = "2h"    # Two hours
  }
}

ExamplesExamples

Creating a single-host clusterCreating a single-host cluster

CLI
Terraform

To create a cluster with a single host, provide a single --host parameter.

Create a Managed Service for MongoDB cluster with the following test specifications:

  • Name: mymg.
  • Environment: production.
  • Network: default.
  • Security group ID: enp6saqnq4ie244g67sb.
  • One s2.micro host in the b0rcctk2rvtr******** subnet, in the ru-central1-a availability zone.
  • Network SSD storage (network-ssd): 20 GB.
  • One user: user1, password: user1user1.
  • One database: db1.
  • Deletion protection: Enabled.

Run the following command:

yc managed-mongodb cluster create \
  --name mymg \
  --environment production \
  --network-name default \
  --security-group-ids enp6saqnq4ie244g67sb \
  --mongod-resource-preset s2.micro \
  --host zone-id=ru-central1-a,subnet-id=b0rcctk2rvtr******** \
  --mongod-disk-size 20 \
  --mongod-disk-type network-ssd \
  --user name=user1,password=user1user1 \
  --database name=db1 \
  --deletion-protection

Create a Managed Service for MongoDB cluster and a network for it with the following test specifications:

  • Name: mymg.

  • Version: 7.0.

  • Environment: PRODUCTION.

  • Cloud ID: b1gq90dgh25bebiu75o.

  • Folder ID: b1gia87mbaomkfvsleds.

  • Network: mynet.

  • Host class: s2.micro.

  • Number of host blocks: 1.

  • Subnet: mysubnet. Network settings:

    • Availability zone: ru-central1-a.
    • Range: 10.5.0.0/24.
  • Security group: mymg-sg. The group rules allow TCP connections to the cluster from the internet via port 27018.

  • Network SSD storage: network-ssd.

  • Storage size: 20 GB.

  • user1 user.

  • Password: user1user1.

  • Database: db1.

  • Deletion protection: Enabled.

Configuration file for a single-host cluster:

resource "yandex_mdb_mongodb_cluster" "mymg" {
  name                = "mymg"
  environment         = "PRODUCTION"
  network_id          = yandex_vpc_network.mynet.id
  security_group_ids  = [ yandex_vpc_security_group.mymg-sg.id ]
  deletion_protection = true

  cluster_config {
    version = "7.0"
  }

  resources_mongod {
    resource_preset_id = "s2.micro"
    disk_type_id       = "network-ssd"
    disk_size          = 20
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
  }
}

resource "yandex_mdb_mongodb_database" "db1" {
  cluster_id = yandex_mdb_mongodb_cluster.mymg.id
  name       = "db1"
}

resource "yandex_mdb_mongodb_user" "user1" {
  cluster_id = yandex_mdb_mongodb_cluster.mymg.id
  name       = "user1"
  password   = "user1user1"
  permission {
    database_name = "db1"
  }
  depends_on = [
    yandex_mdb_mongodb_database.db1
  ]
}

resource "yandex_vpc_network" "mynet" {
  name = "mynet"
}

resource "yandex_vpc_security_group" "mymg-sg" {
  name       = "mymg-sg"
  network_id = yandex_vpc_network.mynet.id

  ingress {
    description    = "MongoDB"
    port           = 27018
    protocol       = "TCP"
    v4_cidr_blocks = [ "0.0.0.0/0" ]
  }
}

resource "yandex_vpc_subnet" "mysubnet" {
  name           = "mysubnet"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.mynet.id
  v4_cidr_blocks = ["10.5.0.0/24"]
}

Creating sharded clustersCreating sharded clusters

You can create Managed Service for MongoDB clusters with standard or advanced sharding. For more information about sharding types, see Sharding management.

Standard shardingStandard sharding

Create a Managed Service for MongoDB cluster and a network for it with multiple hosts:

  • One MONGOD host
  • Three MONGOINFRA hosts

Cluster test specifications:

  • Name: mymg.
  • Environment: PRODUCTION.
  • Deletion protection: Enabled.
  • Version: 7.0.
  • Database: db1.
  • user1 user.
  • Password: user1user1.
  • MONGOD host class: s2.micro.
  • MONGOINFRA host class: c3-c2-m4.
  • Network SSD storage: network-ssd.
  • Storage size: 10 GB.

Network specifications:

  • Network: mynet.

  • Security group: mymg-sg with enp6saqnq4ie244g67sb ID. In Terraform, a group is created with the rule allowing TCP connections to the cluster from the internet on port 27018.

  • Subnet: mysubnet.

  • Availability zone: ru-central1-a.

  • Range: 10.5.0.0/24 (only for Terraform).

CLI
Terraform

To create a Managed Service for MongoDB cluster with standard sharding, run this command:

yc managed-mongodb cluster create \
   --name mymg \
   --environment production \
   --deletion-protection \
   --mongodb-version 7.0 \
   --database name=db1 \
   --user name=user1,password=user1user1 \
   --mongod-resource-preset s2.micro \
   --mongod-disk-type network-ssd \
   --mongod-disk-size 10 \
   --host type=mongod,`
     `zone-id=ru-central1-a,`
     `subnet-name=mysubnet \
   --mongoinfra-resource-preset c3-c2-m4 \
   --mongoinfra-disk-type network-ssd \
   --mongoinfra-disk-size 10 \
   --host type=mongoinfra,`
     `zone-id=ru-central1-a,`
     `subnet-name=mysubnet \
   --host type=mongoinfra,`
     `zone-id=ru-central1-a,`
     `subnet-name=mysubnet \
   --host type=mongoinfra,`
     `zone-id=ru-central1-a,`
     `subnet-name=mysubnet \
   --network-name mynet \
   --security-group-ids enp6saqnq4ie244g67sb

The configuration file for a cluster with standard sharding is as follows:

resource "yandex_mdb_mongodb_cluster" "mymg" {
  name                = "mymg"
  environment         = "PRODUCTION"
  network_id          = yandex_vpc_network.mynet.id
  security_group_ids  = [ yandex_vpc_security_group.mymg-sg.id ]
  deletion_protection = true

  cluster_config {
    version = "7.0"
  }

  resources_mongod {
    resource_preset_id = "s2.micro"
    disk_type_id       = "network-ssd"
    disk_size          = 10
  }

  resources_mongoinfra {
    resource_preset_id = "c3-c2-m4"
    disk_type_id       = "network-ssd"
    disk_size          = 10
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongod"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongoinfra"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongoinfra"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongoinfra"
  }

resource "yandex_mdb_mongodb_database" "db1" {
  cluster_id = yandex_mdb_mongodb_cluster.mymg.id
  name       = "db1"
}

resource "yandex_mdb_mongodb_user" "user1" {
  cluster_id = yandex_mdb_mongodb_cluster.mymg.id
  name       = "user1"
  password   = "user1user1"
  permission {
    database_name = "db1"
  }
  depends_on = [
    yandex_mdb_mongodb_database.db1
  ]
}

resource "yandex_vpc_network" "mynet" {
  name = "mynet"
}

resource "yandex_vpc_security_group" "mymg-sg" {
  name       = "mymg-sg"
  network_id = yandex_vpc_network.mynet.id

  ingress {
    description    = "MongoDB"
    port           = 27018
    protocol       = "TCP"
    v4_cidr_blocks = [ "0.0.0.0/0" ]
  }
}

resource "yandex_vpc_subnet" "mysubnet" {
  name           = "mysubnet"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.mynet.id
  v4_cidr_blocks = ["10.5.0.0/24"]
}

Advanced shardingAdvanced sharding

Create a Managed Service for MongoDB cluster and a network for it with multiple hosts:

  • One MONGOD host
  • Two MONGOS hosts
  • Three MONGOCFG hosts

Cluster test specifications:

  • Name: mymg.
  • Environment: PRODUCTION.
  • Deletion protection: Enabled.
  • Version: 7.0.
  • Database: db1.
  • user1 user.
  • Password: user1user1.
  • Host class: s2.micro.
  • Network SSD storage: network-ssd.
  • Storage size: 10 GB.

Network specifications:

  • Network: mynet.
  • Security group: mymg-sg with enp6saqnq4ie244g67sb ID. In Terraform, a group is created with the rule allowing TCP connections to the cluster from the internet on port 27018.
  • Subnet: mysubnet.
  • Availability zone: ru-central1-a.
  • Range: 10.5.0.0/24 (only for Terraform).
CLI
Terraform

To create a Managed Service for MongoDB cluster with advanced sharding, run this command:

yc managed-mongodb cluster create \
  --name mymg \
  --environment production \
  --deletion-protection \
  --mongodb-version 7.0 \
  --database name=db1 \
  --user name=user1,password=user1user1 \
  --mongod-resource-preset s2.micro \
  --mongod-disk-type network-ssd \
  --mongod-disk-size 10 \
  --host type=mongod,`
    `zone-id=ru-central1-a,`
    `subnet-name=mysubnet \
  --mongos-resource-preset s2.micro \
  --mongos-disk-type network-ssd \
  --mongos-disk-size 10 \
  --host type=mongos,`
    `zone-id=ru-central1-a,`
    `subnet-name=mysubnet \
  --host type=mongos,`
    `zone-id=ru-central1-a,`
    `subnet-name=mysubnet \
  --mongocfg-resource-preset s2.micro \
  --mongocfg-disk-type network-ssd \
  --mongocfg-disk-size 10 \
  --host type=mongocfg,`
    `zone-id=ru-central1-a,`
    `subnet-name=mysubnet \
  --host type=mongocfg,`
    `zone-id=ru-central1-a,`
    `subnet-name=mysubnet \
  --host type=mongocfg,`
    `zone-id=ru-central1-a,`
    `subnet-name=mysubnet \
  --network-name mynet \
  --security-group-ids enp6saqnq4ie244g67sb

The configuration file for a cluster with advanced sharding is as follows:

resource "yandex_mdb_mongodb_cluster" "mymg" {
  name                = "mymg"
  environment         = "PRODUCTION"
  network_id          = yandex_vpc_network.mynet.id
  security_group_ids  = [ yandex_vpc_security_group.mymg-sg.id ]
  deletion_protection = true

  cluster_config {
    version = "7.0"
  }

  resources_mongod {
    resource_preset_id = "s2.micro"
    disk_type_id       = "network-ssd"
    disk_size          = 10
  }

  resources_mongos {
    resource_preset_id = "s2.micro"
    disk_type_id       = "network-ssd"
    disk_size          = 10
  }

  resources_mongocfg {
    resource_preset_id = "s2.micro"
    disk_type_id       = "network-ssd"
    disk_size          = 10
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongod"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongos"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongos"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongocfg"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongocfg"
  }

  host {
    zone_id   = "ru-central1-a"
    subnet_id = yandex_vpc_subnet.mysubnet.id
    type      = "mongocfg"
  }
}

resource "yandex_mdb_mongodb_database" "db1" {
  cluster_id = yandex_mdb_mongodb_cluster.mymg.id
  name       = "db1"
}

resource "yandex_mdb_mongodb_user" "user1" {
  cluster_id = yandex_mdb_mongodb_cluster.mymg.id
  name       = "user1"
  password   = "user1user1"
  permission {
    database_name = "db1"
  }
  depends_on = [
    yandex_mdb_mongodb_database.db1
  ]
}

resource "yandex_vpc_network" "mynet" {
  name = "mynet"
}

resource "yandex_vpc_security_group" "mymg-sg" {
  name       = "mymg-sg"
  network_id = yandex_vpc_network.mynet.id

  ingress {
    description    = "MongoDB"
    port           = 27018
    protocol       = "TCP"
    v4_cidr_blocks = [ "0.0.0.0/0" ]
  }
}

resource "yandex_vpc_subnet" "mysubnet" {
  name           = "mysubnet"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.mynet.id
  v4_cidr_blocks = ["10.5.0.0/24"]
}

Was the article helpful?

Previous
Information about existing clusters
Next
Updating cluster settings
© 2025 Direct Cursus Technology L.L.C.