AWS aws-backup high security documentation change

Service: aws-backup · 2025-05-31 · Security-related high

File: aws-backup/latest/devguide/restoring-ec2.md

Summary

Added BlockDeviceMappings documentation and troubleshooting for KMS key issues in cross-account/region restores

Security assessment

The changes address potential security risks by documenting encryption requirements and KMS key management during restores. Specific guidance on cross-account/cross-region key handling helps prevent data exposure and restore failures due to encryption misconfigurations.

Diff

diff --git a/aws-backup/latest/devguide/restoring-ec2.md b/aws-backup/latest/devguide/restoring-ec2.md
index eae171d10..ce9e6165d 100644
--- a//aws-backup/latest/devguide/restoring-ec2.md
+++ b//aws-backup/latest/devguide/restoring-ec2.md
@@ -5 +5 @@
-Use the AWS Backup console to restore Amazon EC2 recovery pointsRestore Amazon EC2 with AWS CLI
+Use the AWS Backup console to restore Amazon EC2 recovery pointsRestore Amazon EC2 with AWS CLITroubleshooting
@@ -92,0 +93 @@ The following list is the accepted metadata you can pass to restore an Amazon EC
+    BlockDeviceMappings
@@ -99,0 +101,56 @@ AWS Backup accepts the following information-only attributes. However, including
+[`BlockDeviceMappings`](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ami-block-device-mapping.html#create-ami-bdm) is an optional parameter you can include. AWS Backup supports the following `BlockDeviceMappings` attributes.
+
+###### Note
+
+`SnapshotId` and `OutpostArn` are not supported.
+    
+    
+    {
+      "BlockDeviceMappings": [
+        {
+            "DeviceName" : string,
+            "NoDevice" : string,
+            "VirtualName" : string,
+            "Ebs": {
+                "DeleteOnTermination": boolean,
+                "Iops": number,
+                "VolumeSize": number,
+                "VolumeType": string,
+                "Throughput": number,
+                "Encrypted": boolean,
+                "KmsKeyId": string
+            }
+        }
+     }
+
+For example:
+    
+    
+    {
+      "BlockDeviceMappings": [
+        {
+          "DeviceName": "/def/tuvw",
+          "Ebs": {
+            "DeleteOnTermination": true,
+            "Iops": 3000,
+            "VolumeSize": 16,
+            "VolumeType": "gp3",
+            "Throughput": 125,
+            "Encrypted": true,
+            "KmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/ab3cde45-67f8-9g01-hi2j-3456klmno7p8"
+          }
+        },
+        {
+          "DeviceName": "/abc/xyz",
+          "Ebs": {
+            "DeleteOnTermination": false,
+            "Iops": 3000,
+            "VolumeSize": 16,
+            "VolumeType": "gp3",
+            "Throughput": 125,
+            "Encrypted": false
+          }
+        }
+      ]
+    }
+
@@ -101,0 +159,40 @@ You can also restore an Amazon EC2 instance without including any stored paramet
+###### Important
+
+If you do not override the AWS KMS key in the `BlockDeviceMappings` when restoring from cross-account or cross-Region backups, your restore might fail. For more information, see Troubleshoot Amazon EC2 instance restore issues.
+
+## Troubleshoot Amazon EC2 instance restore issues
+
+###### Troubleshooting issues
+
+  * Cross-account restore failures
+
+  * Cross-Region restore failures
+
+
+
+
+### Cross-account restore failures
+
+**Description:** Amazon EC2 instance restore fails when attempting to restore from a backup that is shared with your account.
+
+**Possible issues:** Your account might not have access to the AWS KMS keys used to encrypt the source volumes in the sharing account. The KMS keys might not be shared with your account.
+
+Or, the volumes attached to the source instance are unencrypted.
+
+**Solution:** To resolve this issue, set the `encrypted` attribute to `true`, and do one of the following:
+
+  * Override the KMS keys in the `BlockDeviceMappings` and specify a KMS key that you own in your account.
+
+  * Request the owning account to grant you access to the KMS keys used to encrypt the volumes by updating the KMS key policy. For more information, see [Allow users in other accounts to use a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html).
+
+
+
+
+### Cross-Region restore failures
+
+**Description:** Amazon EC2 instance restore fails when attempting to restore from a cross-Region backup.
+
+**Issue:** The volumes in the backup might be encrypted with single-Region AWS KMS keys that are not available in the destination Region. Or, the volumes attached to the source instance are unencrypted.
+
+**Solution:** To resolve this issue, set the `encrypted` attribute to `true`, and override the KMS key in the `BlockDeviceMappings` with a KMS key in the destination Region.
+