Sharing Amazon DocumentDB Cluster Snapshots

In Amazon DocumentDB, you can share manual cluster snapshots, which can be copied by authorized AWS accounts. You can share encrypted or unencrypted manual snapshots. When sharing an unencrypted snapshot, authorized AWS accounts can restore the cluster directly from the snapshot instead of making a copy of it and restoring from that. However, you can’t restore a cluster from a snapshot that is both shared and encrypted. Instead, you can make a copy of the cluster and restore the cluster from that copy. For more information about copying a snapshot, see Copying Amazon DocumentDB Cluster Snapshots.

Note

You can’t share an Amazon DocumentDB automated cluster snapshot. As a workaround, you can create a manual snapshot by copying the automated snapshot, and then share that copy. For more information about copying a snapshot, see Copying Amazon DocumentDB Cluster Snapshots. For more information about restoring a cluster from a snapshot, see Restoring from a Cluster Snapshot.

You can share a manual snapshot with up to 20 other AWS accounts. You can also share an unencrypted manual snapshot as public, which makes the snapshot available to all accounts. When sharing a snapshot as public, ensure that none of your private information is included in any of your public snapshots.

When sharing manual snapshots with other AWS accounts, and you restore a cluster from a shared snapshot using the AWS CLI or the Amazon DocumentDB API, you must specify the Amazon Resource Name (ARN) of the shared snapshot as the snapshot identifier.

Sharing an Encrypted Snapshot

The following restrictions apply to sharing encrypted snapshots:

  • You can’t share encrypted snapshots as public.

  • You can’t share a snapshot that has been encrypted using the default AWS KMS encryption key of the account that shared the snapshot.

Follow these steps to share encrypted snapshots.

  1. Share the AWS Key Management Service (AWS KMS) encryption key that was used to encrypt the snapshot with any accounts that you want to be able to access the snapshot.

    You can share AWS KMS encryption keys with another AWS accounts by adding the other accounts to the AWS KMS key policy. For details on updating a key policy, see Using Key Policies in AWS KMS in the AWS Key Management Service Developer Guide. For an example of creating a key policy, see Creating an IAM Policy to Enable Copying of the Encrypted Snapshot later in this topic.

  2. Use the AWS CLI, as shown below, to share the encrypted snapshot with the other accounts.

Allowing Access to an AWS KMS Encryption Key

For another AWS account to copy an encrypted snapshot shared from your account, the account that you share your snapshot with must have access to the AWS KMS key that encrypted the snapshot. To allow another account access to an AWS KMS key, update the key policy for the AWS KMS key with the ARN of the account that you are sharing to as a principal in the AWS KMS key policy. Then allow the kms:CreateGrant action.

After you give an account access to your AWS KMS encryption key, to copy your encrypted snapshot, that account must create an AWS Identity and Access Management (IAM) user if it doesn’t already have one. In addition, that account must also attach an IAM policy to that IAM user that allows the user to copy an encrypted snapshot using your AWS KMS key. The account must be an IAM user and cannot be a root AWS account identity due to AWS KMS security restrictions.

In the following key policy example, user 123451234512 is the owner of the AWS KMS encryption key. User 123456789012 is the account that the key is being shared with. This updated key policy gives the account access to the AWS KMS key. It does this by including the ARN for the root AWS account identity for user 123456789012 as a principal for the policy, and by allowing the kms:CreateGrant action.

  1. {
  2.     "Id": "key-policy-1",
  3.     "Version": "2012-10-17",
  4.     "Statement": [
  5.         {
  6.             "Sid": "Allow use of the key",
  7.             "Effect": "Allow",
  8.             "Principal": {"AWS": [
  9.                 "arn:aws:iam::123451234512:user/KeyUser",
  10.                 "arn:aws:iam::123456789012:root"
  11.             ]},
  12.             "Action": [
  13.                 "kms:CreateGrant",
  14.                 "kms:Encrypt",
  15.                 "kms:Decrypt",
  16.                 "kms:ReEncrypt*",
  17.                 "kms:GenerateDataKey*",
  18.                 "kms:DescribeKey"
  19.             ],
  20.             "Resource": "*"},
  21.             {
  22.             "Sid": "Allow attachment of persistent resources",
  23.             "Effect": "Allow",
  24.             "Principal": {"AWS": [
  25.                 "arn:aws:iam::123451234512:user/KeyUser",
  26.                 "arn:aws:iam::123456789012:root"
  27.             ]},
  28.             "Action": [
  29.                 "kms:CreateGrant",
  30.                 "kms:ListGrants",
  31.                 "kms:RevokeGrant"
  32.             ],
  33.             "Resource": "*",
  34.             "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}}
  35.         }
  36.     ]
  37. }

Creating an IAM Policy to Enable Copying of the Encrypted Snapshot

When the external AWS account has access to your AWS KMS key, the owner of that account can create a policy to allow an IAM user that is created for the account to copy an encrypted snapshot that is encrypted with that AWS KMS key.

The following example shows a policy that can be attached to an IAM user for AWS account 123456789012. The policy enables the IAM user to copy a shared snapshot from account 123451234512 that has been encrypted with the AWS KMS key c989c1dd-a3f2-4a5d-8d96-e793d082ab26 in the us-west-2 Region.

  1. {
  2.     "Version": "2012-10-17",
  3.     "Statement": [
  4.         {
  5.             "Sid": "AllowUseOfTheKey",
  6.             "Effect": "Allow",
  7.             "Action": [
  8.                 "kms:Encrypt",
  9.                 "kms:Decrypt",
  10.                 "kms:ReEncrypt*",
  11.                 "kms:GenerateDataKey*",
  12.                 "kms:DescribeKey",
  13.                 "kms:CreateGrant",
  14.                 "kms:RetireGrant"
  15.             ],
  16.             "Resource": ["arn:aws:kms:us-west-2:123451234512:key/c989c1dd-a3f2-4a5d-8d96-e793d082ab26"]
  17.         },
  18.         {
  19.             "Sid": "AllowAttachmentOfPersistentResources",
  20.             "Effect": "Allow",
  21.             "Action": [
  22.                 "kms:CreateGrant",
  23.                 "kms:ListGrants",
  24.                 "kms:RevokeGrant"
  25.             ],
  26.             "Resource": ["arn:aws:kms:us-west-2:123451234512:key/c989c1dd-a3f2-4a5d-8d96-e793d082ab26"],
  27.             "Condition": {
  28.                 "Bool": {
  29.                     "kms:GrantIsForAWSResource": true
  30.                 }
  31.             }
  32.         }
  33.     ]
  34. }

For details on updating a key policy, see Using Key Policies in AWS KMS in the AWS Key Management Service Developer Guide.

Sharing a Snapshot

To share a snapshot, use the Amazon DocumentDB modify-db-snapshot-attribute operation. Use the --values-to-add parameter to add a list of the IDs for the AWS accounts that are authorized to restore the manual snapshot.

The following example permits two AWS account identifiers, 123451234512 and 123456789012, to restore the snapshot named manual-snapshot1. It also removes the all attribute value to mark the snapshot as private.

For Linux, macOS, or Unix:

  1. aws docdb modify-db-cluster-snapshot-attribute \
  2.     --db-cluster-snapshot-identifier sample-cluster-snapshot \
  3.     --attribute-name restore \
  4.     --values-to-add '["123451234512","123456789012"]'

For Windows:

  1. aws docdb modify-db-cluster-snapshot-attribute ^
  2.     --db-cluster-snapshot-identifier sample-cluster-snapshot ^
  3.     --attribute-name restore ^
  4.     --values-to-add '["123451234512","123456789012"]'

Output from this operation looks something like the following.

  1. {
  2.     "DBClusterSnapshotAttributesResult": {
  3.         "DBClusterSnapshotIdentifier": "sample-cluster-snapshot",
  4.         "DBClusterSnapshotAttributes": [
  5.             {
  6.                 "AttributeName": "restore",
  7.                 "AttributeValues": [
  8.                     "123451234512",
  9.                     "123456789012"
  10.                 ]
  11.             }
  12.         ]
  13.     }
  14. }

To remove an AWS account identifier from the list, use the --values-to-remove parameter. The following example prevents AWS account ID 123456789012 from restoring the snapshot.

For Linux, macOS, or Unix:

  1. aws docdb modify-db-cluster-snapshot-attribute \
  2.     --db-cluster-snapshot-identifier sample-cluster-snapshot \
  3.     --attribute-name restore \
  4.     --values-to-remove '["123456789012"]'

For Windows:

  1. aws docdb modify-db-cluster-snapshot-attribute ^
  2.     --db-cluster-snapshot-identifier sample-cluster-snapshot ^
  3.     --attribute-name restore ^
  4.     --values-to-remove '["123456789012"]'

Output from this operation looks something like the following.

  1. {
  2.     "DBClusterSnapshotAttributesResult": {
  3.         "DBClusterSnapshotIdentifier": "sample-cluster-snapshot",
  4.         "DBClusterSnapshotAttributes": [
  5.             {
  6.                 "AttributeName": "restore",
  7.                 "AttributeValues": [
  8.                     "123451234512"
  9.                 ]
  10.             }
  11.         ]
  12.     }
  13. }