How can I troubleshoot restoring my ElastiCache cluster from S3?

Short description

The following are common reasons why restoring an ElastiCache backup from Amazon S3 fails:

• You're attempting to restore a backup outside of the backup constraints.
• ElastiCache couldn't retrieve the file from Amazon S3.
• The ElastiCache backup file is located in an Amazon S3 bucket in another Region.
• You're restoring an .rdb file containing multiple databases to an ElastiCache (cluster mode enabled) cluster.

Resolution

You're attempting to restore a backup outside of the backup constraints

When restoring an ElastiCache for Redis backup, it's important to note the following backup constraints:

• You can't restore from a backup created using a Redis (cluster mode enabled) cluster to a Redis (cluster mode disabled) cluster.

• When restoring a backup made from an ElastiCache (cluster mode enabled) cluster, you can't select the cluster mode disabled option in the ElastiCache console. Only the cluster mode enabled option is available.
• When you export an ElastiCache (cluster mode enabled) cluster backup to Amazon S3, multiple .rdb files are created (one for each shard). If you try to seed the backup from Amazon S3, you can reference only one backup (.rdb). This results in seeding a single shard's keys. Trying to circumvent this by including a wildcard results in the following error:
  Error: Object or bucket does not exist for S3 object: examplebucket/cluster-mode-enabled-*.rdb.

• You can't restore a backup from a cluster that uses data tiering. For example, you can't restore a r6gd node into a cluster that doesn't use data tiering, such as a r6g node.

• Due to limitations of ElastiCache Redis data tiering, you can't export the backup to Amazon S3. So, you can't restore an ElastiCache data tiering backup from S3.

• You can't restore from a Redis (cluster mode disabled) cluster to a Redis (cluster mode enabled) cluster if the .rdb file references more than one database. Attempting to do this results in the following error:
  Error: To restore a snapshot in cluster mode, all keys in the RDB file should reside in DB 0.

ElastiCache couldn't retrieve the file from Amazon S3

This error occurs when ElastiCache doesn't have the necessary permissions to access the ElastiCache backup stored in the S3 bucket. You can confirm the permissions issue by reviewing ElastiCache Events.

The following example ElastiCache Event shows that Redis replication group "test" creation failed because ElastiCache couldn't retrieve the backup file from S3:

Restore from snapshot failed for node group 0001 in replication group test. Failed to retrieve file from S3

After determining that the cause of the error is that ElastiCache couldn't retrieve the file from Amazon S3, confirm that your Region is one of the following:

• An opt-in Region
• China (Beijing) and China (Ningxia)
• AWS GovCloud (US-West)
• A default Region

An opt-in Region requires a bucket policy allowing ElastiCache to retrieve the backup file from Amazon S3.

If your S3 bucket is located in one of the following Regions, you must allow the ElastiCache service access to the backup file in S3:

• China (Beijing) and China (Ningxia)
• AWS GovCloud (US-West)
• A default Region

Note: The canonical ID for the China (Beijing), China (Ningxia), and AWS GovCloud (US-West) Regions are different from the default AWS Regions:

China (Beijing) and China (Ningxia)

Canonical ID: b14d6a125bdf69854ed8ef2e71d8a20b7c490f252229b806e514966e490b8d83

AWS GovCloud (US-West) Region

Canonical ID: 40fa568277ad703bd160f66ae4f83fc9dfdfd06c2f1b5060ca22442ac3ef8be6

AWS default Regions

Canonical ID: 540804c33a284a299d2547575ce1010f2312ef3da9b3a053c8bc45bf233e4353

After granting ElastiCache access to the .rdb backup object in Amazon S3 using a canonical ID or bucket policy, restore the Redis cluster.

The ElastiCache backup file is located in an Amazon S3 bucket in another Region

The following error message indicates that you're trying to restore an ElastiCache backup that's located in an Amazon S3 bucket within another Region:

"Permission denied to access S3 object. Please use the S3 object in the same region."

To resolve this issue, do the following:

1.    Copy the backup (.rdb) from the S3 bucket that contains the backup to an S3 bucket located in the region where the Redis cluster is being restored.

The following is an example AWS Command Line Interface (AWS CLI) command that you can use to copy between Amazon S3 buckets in different Regions:

aws s3 cp s3://SourceBucketName/BackupName.rdb s3://DestinationBucketName/BackupName.rdb --acl bucket-owner-full-control --source-region SourceRegionName --region DestinationRegionName

Note: If you receive errors when running AWS CLI commands, make sure that you're using the most recent version of the AWS CLI.

2.    After the copy is completed, confirm that the backup (.rdb) object has the correct permissions assigned to it in the form of a canonical ID or a bucket policy. See the previous section for the correct canonical IDs.

Now that the backup object is copied to the correct Region and the correct permissions are applied, you can continue to restore the cluster.

You're restoring an .rdb file containing multiple databases to an ElastiCache (cluster mode enabled) cluster

You can't restore a Redis backup (.rdb) file containing multiple databases to an ElastiCache (cluster mode enabled) cluster. ElastiCache (cluster mode enabled) doesn't support multiple databases. All the keys should reside in DB0. You can confirm if this is the cause for the restore failure by reviewing ElastiCache Events.

The following example ElastiCache Event shows that Redis replication group "test" creation failed due to the .rdb file containing multiple databases.

Restore from snapshot failed for node group 0001 in replication group test. To restore a snapshot in cluster mode, all keys in the RDB file should reside in DB 0. Snapshot ID: arn:aws:s3:::example-bucket/multidb.rdb

To correct this issue, do the following:

1.    Make sure that that all the keys are migrated to a single database.

Note: If the source database is located on ElastiCache Redis, the migrate command isn't supported.

2.    After all keys are on the same database, you can create a local backup of your Redis database, upload the backup to Amazon S3 and continue to restore to an ElastiCache (cluster mode enabled) cluster.

---