Managing backups in Yandex StoreDoc

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

The folder used by default is the one specified when creating the CLI 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 options.

To restore a cluster from a backup:

1. View the description of the CLI command for restoring a Yandex StoreDoc cluster:

   yc managed-mongodb cluster restore --help
   

2. Get the list of available Yandex StoreDoc cluster backups:

   yc managed-mongodb backup list
   

   Result:

   +--------------------------+---------------------+----------------------+---------------------+--------+-----------+
   |            ID            |     CREATED AT      |  SOURCE CLUSTER ID   |     STARTED AT      |  SIZE  |   TYPE    |
   +--------------------------+---------------------+----------------------+---------------------+--------+-----------+
   | c9qlk4v13uq7********:... | 2020-08-10 12:00:00 | c9qlk4v13uq7******** | 2020-08-10 11:55:17 | 3.3 KB | AUTOMATED |
   | ...                                                                                         |                    |
   +--------------------------+---------------------+----------------------+---------------------+--------+-----------+
   

   You can see the backup completion time in the CREATED AT column of the available backups list. It is formatted as yyyy-mm-dd hh:mm:ss, e.g., 2020-08-10 12:00:00 in the example above. You can restore your cluster to any point in time since the backup was created.

3. Run the command below to create a new cluster from a backup. Note that these examples do not show all available command options.

   For a non-sharded cluster:

   yc managed-mongodb cluster restore \
      --backup-id <backup_ID> \
      --recovery-target-timestamp <time_point> \
      --mongodb-version <Yandex_StoreDoc_version> \
      --name <new_cluster_name> \
      --environment <environment> \
      --network-name <network_name> \
      --host zone-id=<availability_zone>,`
            `subnet-id=<subnet_ID> \
      --mongod-resource-preset <host_class> \
      --mongod-disk-size <storage_size_in_GB> \
      --mongod-disk-type <disk_type> \
      --disk-size-autoscaling mongod-disk-size-limit=<max_storage_size_in_GB>,`
                             `mongod-planned-usage-threshold=<scheduled_expansion_percentage>,`
                             `mongod-emergency-usage-threshold=<immediate_expansion_percentage> \
      --maintenance-window type=<maintenance_type>,`
                          `day=<day_of_week>,`
                          `hour=<hour> \
      --performance-diagnostics=<enable_diagnostics>
   

   For a sharded cluster:

   yc managed-mongodb cluster restore \
      --backup-id <backup_ID> \
      --recovery-target-timestamp <time_point> \
      --mongodb-version <Yandex_StoreDoc_version> \
      --name <new_cluster_name> \
      --environment <environment> \
      --network-name <network_name> \
      --host zone-id=<availability_zone>,`
            `subnet-id=<subnet_ID>,`
            `type=mongod,`
            `shard-name=<shard_name> \
      --mongod-resource-preset <host_class> \
      --mongod-disk-size <storage_size_in_GB> \
      --mongod-disk-type <disk_type> \
      --host zone-id=<availability_zone>,`
            `subnet-id=<subnet_ID>,`
            `type=<host_type> \
      ...
      --host zone-id=<availability_zone>,`
            `subnet-id=<subnet_ID>,`
            `type=<host_type> \
      --<host_type>-resource-preset <host_class> \
      --<host_type>-disk-size <storage_size_in_GB> \
      --<host_type>-disk-type <disk_type> \
      --disk-size-autoscaling mongod-disk-size-limit=<max_storage_size_in_GB>,`
                             `mongod-planned-usage-threshold=<scheduled_expansion_percentage>,`
                             `mongod-emergency-usage-threshold=<immediate_expansion_percentage>,`
                              ...
                             `<host_type>-disk-size-limit=<max_storage_size_in_GB>,`
                             `<host_type>-planned-usage-threshold=<scheduled_expansion_percentage>,`
                             `<host_type>-emergency-usage-threshold=<immediate_expansion_percentage> \
      --maintenance-window type=<maintenance_type>,`
                          `day=<day_of_week>,`
                          `hour=<hour> \
      --performance-diagnostics=<enable_diagnostics>
   

   Where:

   • --backup-id: Backup ID. To restore a sharded cluster, specify the sharded backup ID. Such backups are larger in size.

     To find out the ID, get a list of backups in the folder.

   • --recovery-target-timestamp: Target recovery time for the Yandex StoreDoc cluster, in UNIX time format. If you omit this argument, the cluster will be restored to its state at the time of backup completion.

   • --mongodb-version: Yandex StoreDoc version.

   • --name: New cluster’s name.

   • --environment: Environment, PRESTABLE or PRODUCTION.

   • --network-name: Name of the network the cluster will be deployed in.

   • --mongod-resource-preset: MONGOD host class.

   • --mongod-disk-size: Storage size for MONGOD hosts, GB.

   • --mongod-disk-type: Disk type for MONGOD hosts: network-hdd, network-ssd, or network-ssd-io-m3.

   • --<host_type>-resource-preset, --<host_type>-disk-size, --<host_type>-disk-type: Host parameters controlling cluster sharding. The possible <host_type> values are mongoinfra, mongocfg, or mongos.

   • --disk-size-autoscaling: Storage autoscaling settings. The <host_type> can take the following values: mongod for sharded and non-sharded clusters; mongoinfra, mongocfg, or mongos only for sharded clusters.

     • <host_type>-planned-usage-threshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.

       Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled.

       If you specified a value greater than 0, configure the maintenance schedule.

     • <host_type>-emergency-usage-threshold: Storage usage percentage to trigger an immediate storage expansion.

       Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled. The value of this setting must be greater than or equal to <host_type>-planned-usage-threshold.

     • <host_type>-disk-size-limit: Maximum storage size, in GB, that can be set if the usage percentage reaches one of the specified thresholds.

       If you set it to 0, automatic storage expansion will be disabled.

   • --maintenance-window: Maintenance window settings, applying to both running and stopped clusters. In --maintenance-window, provide one of these two values:

     • anytime: At any time (default).
     • weekly: On a schedule. For this value, also specify the following:
       • day: Day of week, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.
       • hour: Hour of day (UTC), from 1 to 24.

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

1. Get an IAM token for API authentication and put it into an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Create a file named body.json and paste the following code into it:

   {
     "folderId": "<folder_ID>",
     "backupId": "<backup_ID>",
     "name": "<new_cluster_name>",
     "environment": "<environment>",
     "networkId": "<network_ID>",
     "recoveryTargetSpec": {
       "timestamp": "<time_point>"
     },
     "configSpec": {
       "version": "<Yandex_StoreDoc_version>",
       "mongodb": {
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resourcePresetId": "<host_class>",
             "diskSize": "<storage_size_in_bytes>",
             "diskTypeId": "<disk_type>"
           },
           "diskSizeAutoscaling": {
             "plannedUsageThreshold": "<scheduled_expansion_percentage>",
             "emergencyUsageThreshold": "<immediate_expansion_percentage>",
             "diskSizeLimit": "<maximum_storage_size_in_bytes>"
           }
         },
         ...
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resourcePresetId": "<host_class>",
             "diskSize": "<storage_size_in_bytes>",
             "diskTypeId": "<disk_type>"
           },
           "diskSizeAutoscaling": {
             "plannedUsageThreshold": "<scheduled_expansion_percentage>",
             "emergencyUsageThreshold": "<immediate_expansion_percentage>",
             "diskSizeLimit": "<maximum_storage_size_in_bytes>"
           }
         }
       }
     },
     "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>"
       }
     ],
     "maintenanceWindow": {
       "weeklyMaintenanceWindow": {
         "day": "<day_of_week>",
         "hour": "<hour>"
       }
     }
   }
   

   Where:

   • folderId: Folder ID. You can get it from the list of your cloud folders.

   • backupId: Backup ID. To restore a sharded cluster, specify the sharded backup ID. Such backups are larger in size.

     To learn the ID, get the list of backups in the folder.

   • name: New cluster’s name.

   • environment: Cluster environment, PRODUCTION or PRESTABLE.

   • networkId: ID of the network where the cluster will be deployed.

   • recoveryTargetSpec.timestamp: Target recovery time for the Yandex StoreDoc cluster, in UNIX time format. If you omit this argument, the cluster will be restored to its state at the time of backup completion.

   • configSpec: Cluster settings:

     • version: Yandex StoreDoc version, 5.0, 6.0, or 7.0.

     • Yandex StoreDoc host type depends on the sharding type. The possible values are mongod, mongocfg, mongos, and mongoinfra. For a non-sharded cluster, use mongod.

       • resources: Cluster resources:

         • resourcePresetId: Host class.
         • diskSize: Disk size in bytes.
         • diskTypeId: Disk type.

       • diskSizeAutoscaling: Storage autoscaling settings:

         • plannedUsageThreshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled.

           If you specified a value greater than 0, configure the maintenance schedule.

         • emergencyUsageThreshold: Storage usage percentage to trigger an immediate storage expansion.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled. The value of this setting must be greater than or equal to plannedUsageThreshold.

         • diskSizeLimit: Maximum storage size, in bytes, that can be set when storage usage reaches one of the specified thresholds.

           If you set it to 0, automatic storage expansion will be disabled.

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

     • zoneId: Availability zone.
     • subnetId: Subnet ID.
     • assignPublicIp: Internet access to the host via a public IP address, true or false.
     • type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. For a non-sharded cluster, use MONGOD.
     • shardName: Shard name in a sharded cluster.
     • hidden: Specifies whether to hide (true) or display (false) the host.
     • secondaryDelaySecs: Host’s replication lag behind the master.
     • priority: Host priority for master promotion during failover.
     • tags: Host tags.

   • maintenanceWindow: Maintenance window settings, applying to both running and stopped clusters. In maintenanceWindow, provide one of these two values:

     • anytime: Maintenance takes place at any time.

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

       • day: Day of week in DDD format, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.
       • hour: Hour of the day, in HH format. Allowed values range from 1 to 24 hours.

3. Call the Cluster.Restore 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:restore' \
       --data "@body.json"
   

4. 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. Create a file named body.json and paste the following code into it:

   {
     "folder_id": "<folder_ID>",
     "backup_id": "<backup_ID>",
     "name": "<new_cluster_name>",
     "environment": "<environment>",
     "network_id": "<network_ID>",
     "recovery_target_spec": {
       "timestamp": "<time_point>"
     },
     "config_spec": {
       "version": "<Yandex_StoreDoc_version>",
       "mongodb": {
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resource_preset_id": "<host_class>",
             "disk_size": "<storage_size_in_bytes>",
             "disk_type_id": "<disk_type>"
           },
           "disk_size_autoscaling": {
             "planned_usage_threshold": "<scheduled_expansion_percentage>",
             "emergency_usage_threshold": "<immediate_expansion_percentage>",
             "disk_size_limit": "<maximum_storage_size_in_bytes>"
           }
         },
         ...
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resource_preset_id": "<host_class>",
             "disk_size": "<storage_size_in_bytes>",
             "disk_type_id": "<disk_type>"
           },
           "disk_size_autoscaling": {
             "planned_usage_threshold": "<scheduled_expansion_percentage>",
             "emergency_usage_threshold": "<immediate_expansion_percentage>",
             "disk_size_limit": "<maximum_storage_size_in_bytes>"
           }
         }
       }
     },
     "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>"
       }
     ],
     "maintenance_window": {
       "weekly_maintenance_window": {
         "day": "<day_of_week>",
         "hour": "<hour>"
       }
     }
   }
   

   Where:

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

   • backup_id: Backup ID. To restore a sharded cluster, specify the sharded backup ID. Such backups are larger in size.

     To learn the ID, get the list of backups in the folder.

   • name: New cluster’s name.

   • environment: Cluster environment, PRODUCTION or PRESTABLE.

   • network_id: ID of the network where the cluster will be deployed.

   • recovery_target_spec.timestamp: Target recovery time for the Yandex StoreDoc cluster, in UNIX time format. If you omit this setting, the cluster will be restored to the backup’s completion time.

   • config_spec: Cluster settings:

     • version: Yandex StoreDoc version, 5.0, 6.0, or 7.0.

     • Yandex StoreDoc host type depends on the sharding type. The possible values are mongod, mongocfg, mongos, and mongoinfra. For a non-sharded cluster, use mongod.

       • resources: Cluster resources:

         • resource_preset_id: Host class.
         • disk_size: Disk size in bytes.
         • disk_type_id: Disk type.

       • disk_size_autoscaling: Storage autoscaling settings:

         • planned_usage_threshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled.

           If you specified a value greater than 0, configure the maintenance schedule.

         • emergency_usage_threshold: Storage usage percentage to trigger an immediate storage expansion.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled. The value of this setting must be greater than or equal to planned_usage_threshold.

         • disk_size_limit: Maximum storage size, in bytes, that can be set when storage usage reaches one of the specified thresholds.

           If you set it to 0, automatic storage expansion will be disabled.

   • host_specs: Cluster host settings as an array of elements, one per 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, true or false.
     • type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. For a non-sharded cluster, use MONGOD.
     • shard_name: Shard name in a sharded cluster.
     • hidden: Specifies whether to hide (true) or display (false) the host.
     • secondary_delay_secs: Host’s replication lag behind the master.
     • priority: Host priority for master promotion during failover.
     • tags: Host tags.

   • maintenance_window: Maintenance window settings, applying to both running and stopped clusters. In maintenance_window, provide one of these two values:

     • anytime: Maintenance takes place at any time.

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

       • day: Day of week in DDD format, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.
       • hour: Hour of the day, in HH format. Allowed values range from 1 to 24 hours.

4. Call the ClusterService.Restore 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 @ \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.mongodb.v1.ClusterService.Restore \
       < body.json
   

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

1. Get an IAM token for API authentication and put it into an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Create a file named body.json and paste the following code into it:

   {
     "folderId": "<folder_ID>",
     "backupId": "<backup_ID>",
     "name": "<new_cluster_name>",
     "environment": "<environment>",
     "networkId": "<network_ID>",
     "recoveryTargetSpec": {
       "timestamp": "<time>"
     },
     "configSpec": {
       "version": "<Yandex_StoreDoc_version>",
       "mongodb": {
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resourcePresetId": "<host_class>",
             "diskSize": "<storage_size_in_bytes>",
             "diskTypeId": "<disk_type>"
           },
           "diskSizeAutoscaling": {
             "plannedUsageThreshold": "<scheduled_expansion_percentage>",
             "emergencyUsageThreshold": "<immediate_expansion_percentage>",
             "diskSizeLimit": "<maximum_storage_size_in_bytes>"
           }
         },
         ...
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resourcePresetId": "<host_class>",
             "diskSize": "<storage_size_in_bytes>",
             "diskTypeId": "<disk_type>"
           },
           "diskSizeAutoscaling": {
             "plannedUsageThreshold": "<scheduled_expansion_percentage>",
             "emergencyUsageThreshold": "<immediate_expansion_percentage>",
             "diskSizeLimit": "<maximum_storage_size_in_bytes>"
           }
         }
       }
     },
     "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>"
       }
     ],
     "maintenanceWindow": {
       "weeklyMaintenanceWindow": {
         "day": "<day_of_week>",
         "hour": "<hour>"
       }
     },
     "partialRestoreSpec": {
       "whitelist": [<list_of_databases_and_collections_to_restore>],
       "blacklist": [<list_of_databases_and_collections_to_exclude_from_restoring>]
     }
   }
   

   Where:

   • folderId: Folder ID. You can get it from the list of your cloud folders.

   • backupId: Backup ID. To restore a sharded cluster, specify the sharded backup ID. Such backups are larger in size.

     To learn the ID, get the list of backups in the folder.

   • name: New cluster’s name.

   • environment: Cluster environment, PRODUCTION or PRESTABLE.

   • networkId: ID of the network where the cluster will be deployed.

   • recoveryTargetSpec.timestamp: Target recovery time for the Yandex StoreDoc cluster, in UNIX time format. If you omit this argument, the cluster will be restored to its state at the time of backup completion.

   • configSpec: Cluster settings:

     • version: Yandex StoreDoc version, 5.0, 6.0, or 7.0.

     • Yandex StoreDoc host type depends on the sharding type. The possible values are mongod, mongocfg, mongos, and mongoinfra. For a non-sharded cluster, use mongod.

       • resources: Cluster resources:

         • resourcePresetId: Host class.
         • diskSize: Disk size in bytes.
         • diskTypeId: Disk type.

       • diskSizeAutoscaling: Storage autoscaling settings:

         • plannedUsageThreshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled.

           If you specified a value greater than 0, configure the maintenance schedule.

         • emergencyUsageThreshold: Storage usage percentage to trigger an immediate storage expansion.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled. The value of this setting must be greater than or equal to plannedUsageThreshold.

         • diskSizeLimit: Maximum storage size, in bytes, that can be set when storage usage reaches one of the specified thresholds.

           If you set it to 0, automatic storage expansion will be disabled.

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

     • zoneId: Availability zone.
     • subnetId: Subnet ID.
     • assignPublicIp: Internet access to the host via a public IP address, true or false.
     • type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. For a non-sharded cluster, use MONGOD.
     • shardName: Shard name in a sharded cluster.
     • hidden: Specifies whether to hide (true) or display (false) the host.
     • secondaryDelaySecs: Host’s replication lag behind the master.
     • priority: Host priority for master promotion during failover.
     • tags: Host tags.

   • maintenanceWindow: Maintenance window settings, applying to both running and stopped clusters. In maintenanceWindow, provide one of these two values:

     • anytime: Maintenance takes place at any time.

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

       • day: Day of week in DDD format, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.
       • hour: Hour of the day, in HH format. Allowed values range from 1 to 24 hours.

   • partialRestoreSpec: Settings for restoring individual databases and collections:

     • whitelist: List of databases and collections to restore. For example: ["db1", "db2.collection1"].
     • blacklist: List of databases and collections to exclude from restoring. Here is an example: ["db1.collection1"].

     If you specify databases under whitelist, you can use blacklist to exclude specific collections within those databases.
     If the whitelist parameter is not specified, all databases and collections will be restored except those specified under blacklist.

3. Call the Cluster.Restore 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:restore' \
       --data "@body.json"
   

4. 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. Create a file named body.json and paste the following code into it:

   {
     "folder_id": "<folder_ID>",
     "backup_id": "<backup_ID>",
     "name": "<new_cluster_name>",
     "environment": "<environment>",
     "network_id": "<network_ID>",
     "recovery_target_spec": {
       "timestamp": "<time>"
     },
     "config_spec": {
       "version": "<Yandex_StoreDoc_version>",
       "mongodb": {
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resource_preset_id": "<host_class>",
             "disk_size": "<storage_size_in_bytes>",
             "disk_type_id": "<disk_type>"
           },
           "disk_size_autoscaling": {
             "planned_usage_threshold": "<scheduled_expansion_percentage>",
             "emergency_usage_threshold": "<immediate_expansion_percentage>",
             "disk_size_limit": "<maximum_storage_size_in_bytes>"
           }
         },
         ...
         "<Yandex_StoreDoc_host_type>": {
           "resources": {
             "resource_preset_id": "<host_class>",
             "disk_size": "<storage_size_in_bytes>",
             "disk_type_id": "<disk_type>"
           },
           "disk_size_autoscaling": {
             "planned_usage_threshold": "<scheduled_expansion_percentage>",
             "emergency_usage_threshold": "<immediate_expansion_percentage>",
             "disk_size_limit": "<maximum_storage_size_in_bytes>"
           }
         }
       }
     },
     "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>"
       }
     ],
     "maintenance_window": {
       "weekly_maintenance_window": {
         "day": "<day_of_week>",
         "hour": "<hour>"
       }
     },
     "partial_restore_spec": {
       "whitelist": [<list_of_databases_and_collections_to_restore>],
       "blacklist": [<list_of_databases_and_collections_to_exclude_from_restoring>]
     }
   }
   

   Where:

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

   • backup_id: Backup ID. To restore a sharded cluster, specify the sharded backup ID. Such backups are larger in size.

     To learn the ID, get the list of backups in the folder.

   • name: New cluster’s name.

   • environment: Cluster environment, PRODUCTION or PRESTABLE.

   • network_id: ID of the network where the cluster will be deployed.

   • recovery_target_spec.timestamp: Target recovery time for the Yandex StoreDoc cluster, in UNIX time format. If you omit this setting, the cluster will be restored to the backup’s completion time.

   • config_spec: Cluster settings:

     • version: Yandex StoreDoc version, 5.0, 6.0, or 7.0.

     • Yandex StoreDoc host type depends on the sharding type. The possible values are mongod, mongocfg, mongos, and mongoinfra. For a non-sharded cluster, use mongod.

       • resources: Cluster resources:

         • resource_preset_id: Host class.
         • disk_size: Disk size in bytes.
         • disk_type_id: Disk type.

       • disk_size_autoscaling: Storage autoscaling settings:

         • planned_usage_threshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled.

           If you specified a value greater than 0, configure the maintenance schedule.

         • emergency_usage_threshold: Storage usage percentage to trigger an immediate storage expansion.

           Use a value between 0 and 100%. The default value is 0, i.e., automatic expansion is disabled. The value of this setting must be greater than or equal to planned_usage_threshold.

         • disk_size_limit: Maximum storage size, in bytes, that can be set when storage usage reaches one of the specified thresholds.

           If you set it to 0, automatic storage expansion will be disabled.

   • host_specs: Cluster host settings as an array of elements, one per 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, true or false.
     • type: Host type in a sharded cluster, MONGOD, MONGOINFRA, MONGOS, or MONGOCFG. For a non-sharded cluster, use MONGOD.
     • shard_name: Shard name in a sharded cluster.
     • hidden: Specifies whether to hide (true) or display (false) the host.
     • secondary_delay_secs: Host’s replication lag behind the master.
     • priority: Host priority for master promotion during failover.
     • tags: Host tags.

   • maintenance_window: Maintenance window settings, applying to both running and stopped clusters. In maintenance_window, provide one of these two values:

     • anytime: Maintenance takes place at any time.

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

       • day: Day of week in DDD format, i.e., MON, TUE, WED, THU, FRI, SAT, or SUN.
       • hour: Hour of the day, in HH format. Allowed values range from 1 to 24 hours.

   • partial_restore_spec: Settings for restoring individual databases and collections:

     • whitelist: List of databases and collections to restore. For example: ["db1", "db2.collection1"].
     • blacklist: List of databases and collections to exclude from restoring. Here is an example: ["db1.collection1"].

     If you specify databases under whitelist, you can use blacklist to exclude specific collections within those databases.
     If the whitelist parameter is not specified, all databases and collections will be restored except those specified under blacklist.

4. Call the ClusterService.Restore 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 @ \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.mongodb.v1.ClusterService.Restore \
       < body.json
   

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

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

The folder used by default is the one specified when creating the CLI 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 options.

To create a cluster backup:

1. View the description of the CLI command for creating a Yandex StoreDoc backup:

   yc managed-mongodb cluster backup --help
   

2. To create a backup, send the following request, providing the cluster ID or name:

   yc managed-mongodb cluster backup <cluster_name_or_ID>
   

   You can get the cluster name and ID from the list of clusters.

1. Get an IAM token for API authentication and put it into an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Call the Cluster.Backup 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>:backup'
   

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

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

1. Get an IAM token for API authentication and put it into 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.Backup 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.Backup
   

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

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

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

The folder used by default is the one specified when creating the CLI 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 options.

To get a list of Yandex StoreDoc cluster backups in the default folder, run this command:

yc managed-mongodb backup list

Result:

+--------------------------+---------------------+----------------------+---------------------+--------+-----------+
|            ID            |     CREATED AT      |  SOURCE CLUSTER ID   |     STARTED AT      |  SIZE  |   TYPE    |
+--------------------------+---------------------+----------------------+---------------------+--------+-----------+
| c9qlk4v13uq7********:... | 2020-08-10 12:00:00 | c9qlk4v13uq7******** | 2020-08-10 11:55:17 | 3.3 KB | AUTOMATED |
| c9qpm90p3pcg********:... | 2020-08-09 22:01:04 | c9qpm90p3pcg******** | 2020-08-09 21:30:00 | 30 KB  | MANUAL    |
+--------------------------+---------------------+----------------------+---------------------+--------+-----------+

The output table contains the following information:

• Backup ID.
• Backup end time (UTC).
• ID of the backed up cluster.
• Backup start time (UTC).
• Backup size.
• Backup type: AUTOMATED or MANUAL.

1. Get an IAM token for API authentication and put it into an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. To get a list of cluster backups:

   1. Call the Cluster.ListBackups 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>/backups'
      

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

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

3. To list backups for all clusters in your folder:

   1. Call the Backup.List 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/backups'
         --url-query folderId=<folder_ID>
      

      You can get the folder ID from the list of your cloud folders.

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

1. Get an IAM token for API authentication and put it into 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. To get a list of cluster backups:

   1. Call the ClusterService.ListBackups 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.ListBackups
      

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

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

4. To list backups for all clusters in your folder:

   1. Call the BackupService.List 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/backup_service.proto \
          -rpc-header "Authorization: Bearer $IAM_TOKEN" \
          -d '{
                "folder_id": "<folder_ID>"
              }' \
          mdb.api.cloud.yandex.net:443 \
          yandex.cloud.mdb.mongodb.v1.BackupService.List
      

      You can get the folder ID with the list of folders in the cloud.

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

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

The folder used by default is the one specified when creating the CLI 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 options.

To get backup details for a Yandex StoreDoc cluster, run this command:

yc managed-mongodb backup get <backup_ID>

You can get the backup ID with the list of backups.

1. Get an IAM token for API authentication and put it into an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Call the Backup.Get 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/backups/<backup_ID>'
   

   You can get the backup ID with the list of backups.

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

1. Get an IAM token for API authentication and put it into 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 BackupService.Get 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/backup_service.proto \
     -rpc-header "Authorization: Bearer $IAM_TOKEN" \
     -d '{
           "backup_id": "<backup_ID>"
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.mongodb.v1.BackupService.Get
   

   You can get the backup ID with the list of backups.

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

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

The folder used by default is the one specified when creating the CLI 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 options.

To set the retention period for automatic backups, provide the required value for the --backup-retain-period-days argument of the cluster update command:

yc managed-mongodb cluster update <cluster_name_or_ID> \
   --backup-retain-period-days=<retention_period_in_days>

Allowed values range from 7 to 35. The default value is 7.

You can get the cluster ID and name with the list of clusters in the folder.

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

   For more on how to create this file, see Creating a cluster.

   For a complete list of configurable Yandex StoreDoc cluster fields, see this Terraform provider guide.

2. Add the backup_retain_period_days block to the cluster_config section of the Yandex StoreDoc cluster description:

     resource "yandex_mdb_mongodb_cluster" "<cluster_name>" {
       ...
       cluster_config {
         ...
         backup_retain_period_days = <retention_period_in_days>
         }
         ...
       }
       ...
   

   Where backup_retain_period_days is the retention period for automatic backups.

   Allowed values range from 7 to 35. The default value is 7.

3. Validate your settings.

   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. Confirm updating the resources.

   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.

   Timeouts

   The Terraform provider sets the following timeouts for Yandex StoreDoc 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 an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

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

   Warning

   The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

   curl \
       --request PATCH \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --header "Content-Type: application/json" \
       --url 'https://mdb.api.cloud.yandex.net/managed-mongodb/v1/clusters/<cluster_ID>' \
       --data '{
                 "updateMask": "configSpec.backupRetainPeriodDays",
                 "configSpec": {
                   "backupRetainPeriodDays": <backup_retention_in_days>
                 }
               }'
   

   Where:

   • updateMask: Comma-separated string of settings to update.

     Here, we provide only one setting.

   • configSpec.backupRetainPeriodDays: Retention period for automatic backups, in days.

     Allowed values range from 7 to 35. The default value is 7.

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

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

1. Get an IAM token for API authentication and put it into 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.Update method, e.g., via the following gRPCurl request:

   Warning

   The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the update_mask parameter as an array of paths[] strings.

   Format for listing settings

   "update_mask": {
       "paths": [
           "<setting_1>",
           "<setting_2>",
           ...
           "<setting_N>"
       ]
   }
   

   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>",
             "update_mask": {
               "paths": [
                 "config_spec.backup_retain_period_days"
               ]
             },
             "config_spec": {
               "backup_retain_period_days": <backup_retention_in_days>
             }
           }' \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.mongodb.v1.ClusterService.Update
   

   Where:

   • update_mask: List of settings you want to update as an array of strings (paths[]).

     Here, we provide only one setting.

   • config_spec.backup_retain_period_days: Retention period for automatic backups, in days.

     Allowed values range from 7 to 35. The default value is 7.

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

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