Restoring from a Cluster Snapshot

Amazon DocumentDB (with MongoDB compatibility) creates a cluster snapshot of your storage volume. You can create a new cluster by restoring from a cluster snapshot. When you restore the cluster, you provide the name of the cluster snapshot to restore from and a name for the new cluster that is created by the restore. You can’t restore from a snapshot to an existing cluster because a new cluster is created when you restore.

When you are restoring a cluster from a cluster snapshot:

  • This action restores only the cluster, and not the instances for that cluster. You must invoke the create-db-instance action to create instances for the restored cluster, specifying the identifier of the restored cluster in --db-cluster-identifier. You can create instances only after the cluster is available.

  • You cannot restore an encrypted snapshot to an unencrypted cluster. However, you can restore an unencrypted snapshot to an encrypted cluster by specifying the AWS KMS key.

  • To restore a cluster from an encrypted snapshot, you must have access to the AWS KMS key.

Note

You cannot restore a 3.6 cluster to a 4.0 cluster but you can migrate from one cluster version to another. For more information, go to Migrating to Amazon DocumentDB.

Restore from a Cluster Snapshot Using the AWS Management Console

The following procedure shows how to restore an Amazon DocumentDB cluster from a cluster snapshot using the Amazon DocumentDB Management Console.

  1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. In the navigation pane, choose Snapshots, and then choose the button to the left of the snapshot that you want to use to restore a cluster.

    Tip

    If you don’t see the navigation pane on the left side of your screen, choose the menu icon (Restoring from a Cluster Snapshot - 图1) in the upper-left corner of the page.

  3. On the Actions menu, choose Restore.

  4. On the Restore snapshot page, complete the Configuration section.

    1. Cluster identifier — The name for the new cluster. You can accept the Amazon DocumentDB supplied name or type a name that you prefer. The Amazon DocumentDB supplied name is in the format of docdb- plus a UTC timestamp; for example, docdb-*yyyy-mm-dd-hh-mm-ss*.

    2. Instance class — The instance class for the new cluster. You can accept the default instance class or choose an instance class from the drop-down list.

    3. Number of instances — The number of instances you want created with this cluster. You can accept the default of 3 instances (1 primary read/write and 2 read-only replicas) or choose the number of instances from the drop-down list.

  5. If you are satisfied with the cluster configuration, choose Restore cluster and wait while your cluster is restored.

  6. If you prefer to change some configurations, such as specifying a non-default Amazon VPC or security group, choose Show advanced settings from the bottom left of the page, and then continue with the following steps.

    1. Complete the Network settings section.

      • Virtual Private Cloud (VPC) — Accept the current VPC, or choose a VPC from the drop-down list.

      • Subnet Group — Accept the default subnet group, or choose one from the drop-down list.

      • VPC Security Groups — Accept the default (VPC) security group, or choose one from the list.

    2. Complete the Cluster options section.

      • Database port — Accept the default port, 27017, or use the up or down arrow to set the port that you want to use for application connections.

    3. Complete the Encryption section.

      • Encryption at rest — If your snapshot is encrypted, these options are not available to you. If it is not encrypted, you can choose one of the following:

        • To encrypt all your cluster’s data, choose Enable encryption-at-rest. If you choose this option, you must designate a Master key.

        • To not encrypt your cluster’s data, choose Disable encryption-at-rest. If you choose this option, you are finished with the encryption section.

      • Master key — Choose one of the following from the drop-down list:

        • (default) aws/rds — The account number and AWS KMS key ID are listed following this option.

        • Customer-managed key — This option is available only if you created an IAM encryption key in the AWS Identity and Access Management (IAM) console. You can choose the key to encrypt your cluster.

        • Enter a key ARN — In the ARN box, enter the Amazon Resource Name (ARN) for your AWS KMS key. The format of the ARN is arn:aws:kms:<region>:<accountID>:key/<key-id>.

  1. 4.  Complete the **Log exports** section.
  3.     -   **Select the log types to publish to CloudWatch** — Choose one of the following:
  5.         -   **Enabled** — Enables your cluster to export DML logging to Amazon CloudWatch Logs.
  7.         -   **Disabled** — Prevents your cluster from exporting DML logs to Amazon CloudWatch Logs. **Disabled** is the default.
  9.     -   **IAM role**—From the list, choose *RDS Service Linked Role*.
  11. 5.  Complete the **Tags** section.
  13.     -   **Add Tag** — In the *Key* box, enter the name for the tag for your cluster. In the *Value* box, optionally enter the tag value. Tags are used with AWS Identity and Access Management (IAM) policies to manage access to Amazon DocumentDB resources and to control what actions can be applied to the resources.
  15. 6.  Complete the **Deletion protection** section.
  17.     -   **Enable deletion protection** — Protects the cluster from being accidentally deleted. While this option is enabled, you can't delete the cluster.
  1. Choose Restore cluster.

Restore from a Cluster Snapshot Using the AWS CLI

To restore a cluster from a snapshot using the AWS CLI, use the restore-db-cluster-from-snapshot operation with the following parameters. For more information, see RestoreDBClusterFromSnapshot.

  • --db-cluster-identifier — Required. The name of the cluster that is created by the operation. A cluster by this name cannot exist before this operation.

    Cluster naming constraints:

    • Length is [1—63] letters, numbers, or hyphens.

    • First character must be a letter.

    • Cannot end with a hyphen or contain two consecutive hyphens.

    • Must be unique for all clusters across Amazon RDS, Neptune, and Amazon DocumentDB per AWS account, per Region.

  • --snapshot-identifier — Required. The name of the snapshot used to restore from. A snapshot by this name must exist and be in the available state.

  • --engine — Required. Must be docdb.

  • --kms-key-id — Optional. The ARN of the AWS KMS key identifier to use when restoring an encrypted snapshot or encrypting a cluster when restoring from an unencrypted snapshot. Supplying the AWS KMS key ID results in the restored cluster being encrypted with the AWS KMS key, whether or not the snapshot was encrypted.

    The format of the --kms-key-id is arn:aws:kms:<region>:<accountID>:key/<key-id>. If you do not specify a value for the --kms-key-id parameter, then the following occurs:

    • If the snapshot in --snapshot-identifier is encrypted, then the restored cluster is encrypted using the same AWS KMS key that was used to encrypt the snapshot.

    • If the snapshot in --snapshot-identifier is not encrypted, then the restored cluster is not encrypted.

For Linux, macOS, or Unix:

  1. aws docdb restore-db-cluster-from-snapshot \
  2.     --db-cluster-identifier sample-cluster-restore \
  3.     --snapshot-identifier sample-cluster-snapshot \
  4.     --engine docdb \
  5.     --kms-key-id arn:aws:kms:us-east-1:123456789012:key/SAMPLE-KMS-KEY-ID

For Windows:

  1. aws docdb restore-db-cluster-from-snapshot ^
  2.     --db-cluster-identifier sample-cluster-restore ^
  3.     --snapshot-identifier sample-cluster-snapshot ^
  4.     --engine docdb ^
  5.     --kms-key-id arn:aws:kms:us-east-1:123456789012:key/SAMPLE-KMS-KEY-ID

Output from this operation looks something like the following.

  1. {
  2.     "DBCluster": {
  3.         "AvailabilityZones": [
  4.             "us-east-1c",
  5.             "us-east-1b",
  6.             "us-east-1a"
  7.         ],
  8.         "BackupRetentionPeriod": 1,
  9.         "DBClusterIdentifier": "sample-cluster-restore",
  10.         "DBClusterParameterGroup": "default.docdb4.0",
  11.         "DBSubnetGroup": "default",
  12.         "Status": "creating",
  13.         "Endpoint": "sample-cluster-restore.cluster-node.us-east-1.docdb.amazonaws.com",
  14.         "ReaderEndpoint": "sample-cluster-restore.cluster-node.us-east-1.docdb.amazonaws.com",
  15.         "MultiAZ": false,
  16.         "Engine": "docdb",
  17.         "EngineVersion": "4.0.0",
  18.         "Port": 27017,
  19.         "MasterUsername": "<master-user>",
  20.         "PreferredBackupWindow": "02:00-02:30",
  21.         "PreferredMaintenanceWindow": "tue:09:50-tue:10:20",
  22.         "DBClusterMembers": [],
  23.         "VpcSecurityGroups": [
  24.             {                             
  25.                 "VpcSecurityGroupId": "sg-abcdefgh",
  26.                 "Status": "active"
  27.             }
  28.         ],               
  29.         "HostedZoneId": "ABCDEFGHIJKLM",
  30.         "StorageEncrypted": true,
  31.         "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/<sample-key-id>",
  32.         "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  33.         "DBClusterArn": "arn:aws:rds:us-east-1:<accountID>:cluster:sample-cluster-restore",
  34.         "AssociatedRoles": [],
  35.         "ClusterCreateTime": "2020-04-01T01:43:40.871Z",
  36.         "DeletionProtection": true
  37.     }
  38. }

After the cluster status is available, create at least one instance for the cluster.

For Linux, macOS, or Unix:

  1. aws docdb create-db-instance \
  2.     --db-cluster-identifier sample-cluster-restore  \
  3.     --db-instance-identifier sample-cluster-restore-instance \
  4.     --availability-zone us-east-1b \
  5.     --promotion-tier 2 \
  6.     --db-instance-class db.r5.large \
  7.     --engine docdb

For Windows:

  1. aws docdb create-db-instance ^
  2.     --db-cluster-identifier sample-cluster-restore  ^
  3.     --db-instance-identifier sample-cluster-restore-instance ^
  4.     --availability-zone us-east-1b ^
  5.     --promotion-tier 2 ^
  6.     --db-instance-class db.r5.large ^
  7.     --engine docdb

Output from this operation looks something like the following.

  1. {
  2.     "DBInstance": {
  3.         "DBInstanceIdentifier": "sample-cluster-restore-instance",
  4.         "DBInstanceClass": "db.r5.large",
  5.         "Engine": "docdb",
  6.         "DBInstanceStatus": "creating",
  7.         "PreferredBackupWindow": "02:00-02:30",
  8.         "BackupRetentionPeriod": 1,
  9.         "VpcSecurityGroups": [
  10.             {
  11.                 "VpcSecurityGroupId": "sg-abcdefgh",
  12.                 "Status": "active"
  13.             }
  14.         ],
  15.         "AvailabilityZone": "us-west-2b",
  16.         "DBSubnetGroup": {
  17.             "DBSubnetGroupName": "default",
  18.             "DBSubnetGroupDescription": "default",
  19.             "VpcId": "vpc-6242c31a",
  20.             "SubnetGroupStatus": "Complete",
  21.             "Subnets": [
  22.                 {
  23.                     "SubnetIdentifier": "subnet-abcdefgh",
  24.                     "SubnetAvailabilityZone": {
  25.                         "Name": "us-west-2a"
  26.                     },
  27.                     "SubnetStatus": "Active"
  28.                 },
  29.                 {
  30.                     ...
  31.                 }
  32.             ]
  33.         },
  34.         "PreferredMaintenanceWindow": "fri:09:43-fri:10:13",
  35.         "PendingModifiedValues": {},
  36.         "EngineVersion": "4.0.0",
  37.         "AutoMinorVersionUpgrade": true,
  38.         "PubliclyAccessible": false,
  39.         "DBClusterIdentifier": "sample-cluster-restore",
  40.         "StorageEncrypted": true,
  41.         "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/<sample-key-id>",
  42.         "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  43.         "CACertificateIdentifier": "rds-ca-2019",
  44.         "PromotionTier": 2,
  45.         "DBInstanceArn": "arn:aws:rds:us-east-1:<accountID>:db:sample-cluster-restore-instance"
  46.     }
  47. }