Description
The AWSSupport-StartEC2RescueWorkflow runbook runs the provided base64 encoded script (Bash or Powershell) on a helper instance created to rescue your instance. The root volume of your instance is attached and mounted to the helper instance, also known as the EC2Rescue instance. If your instance is Windows, provide a Powershell script. Otherwise, use Bash. The runbook sets some environment variables which you can use in your script. The environment variables contain information about the input you provided, as well as information about the offline root volume. The offline volume is already mounted and ready to use. For example, you can save a Desired State Configuration file to an offline Windows root volume, or chroot to an offline Linux root volume and perform an offline remediation.
AWSSupport-StartEC2RescueWorkflow Run this Automation (console)
Important
Amazon EC2 instances created from Marketplace Amazon Machine Images (AMIs) are not supported by this automation.
Additional Information
To base64 encode a script, you can use either Powershell or Bash. Powershell:
[System.Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes([System.IO.File]::ReadAllText('PATH_TO_FILE')))
Bash:
base64 PATH_TO_FILE
Here is a list of environment variables you can use in your offline scripts, depending on the target OS Windows:
Variable Description Example value
$env:EC2RESCUE_ACCOUNT_ID {{ global:ACCOUNT_ID }} 123456789012
$env:EC2RESCUE_DATE {{ global:DATE }} 2018-09-07
$env:EC2RESCUE_DATE_TIME {{ global:DATE_TIME }} 2018-09-07_18.09.59
$env:EC2RESCUE_EC2RW_DIR EC2Rescue for Windows
installation path C:\Program Files\Amazon
\EC2Rescue
$env:EC2RESCUE_EC2RW_DIR EC2Rescue for Windows
installation path C:\Program Files\Amazon
\EC2Rescue
$env:EC2RESCUE_EXECUTION_ID {{ automation:EXECUTION_ID }} 7ef8008e-219b-4aca-8bb5-65e2e898e20b
$env:EC2RESCUE_OFFLINE_CURRENT_CONTROL_SETOffline Windows Current Control
Set path HKLM:\AWSTempSystem
\ControlSet001
$env:EC2RESCUE_OFFLINE_DRIVE Offline Windows drive letter D:\
$env:EC2RESCUE_OFFLINE_EBS_DEVICEOffline root volume EBS device xvdf
$env:EC2RESCUE_OFFLINE_KERNEL_VEROffline Windows Kernel version 6.1.7601.24214
$env:EC2RESCUE_OFFLINE_OS_ARCHITECTUREOffline Windows architecture AMD64
$env:EC2RESCUE_OFFLINE_OS_CAPTIONOffline Windows caption Windows Server 2008 R2 Datacenter
$env:EC2RESCUE_OFFLINE_OS_TYPEOffline Windows OS type Server
$env:EC2RESCUE_OFFLINE_PROGRAM_FILES_DIROffline Windows Program files
directory path D:\Program Files
$env:EC2RESCUE_OFFLINE_PROGRAM_FILES_X86_DIROffline Windows Program files
x86 directory path D:\Program Files (x86)
$env:EC2RESCUE_OFFLINE_REGISTRY_DIROffline Windows registry
directory path D:\Windows\System32\config
AWSSupport-StartEC2RescueWorkflow
Variable Description Example value
$env:EC2RESCUE_OFFLINE_SYSTEM_ROOTOffline Windows system root
directory path D:\Windows
$env:EC2RESCUE_REGION {{ global:REGION }} us-west-1
$env:EC2RESCUE_S3_BUCKET {{ S3BucketName }} mybucket
$env:EC2RESCUE_S3_PREFIX {{ S3Prefix }} myprefix/
$env:EC2RESCUE_SOURCE_INSTANCE{{ InstanceId }} i-abcdefgh123456789
$script:EC2RESCUE_OFFLINE_WINDOWS_INSTALLOffline Windows Installation
metadata Customer Powershell Object
Linux:
Variable Description Example value
EC2RESCUE_ACCOUNT_ID {{ global:ACCOUNT_ID }} 123456789012
EC2RESCUE_DATE {{ global:DATE }} 2018-09-07
EC2RESCUE_DATE_TIME {{ global:DATE_TIME }} 2018-09-07_18.09.59 EC2RESCUE_EC2RL_DIR EC2Rescue for Linux installation
path /usr/local/ec2rl-1.1.3
EC2RESCUE_EXECUTION_ID {{ automation:EXECUTION_ID }} 7ef8008e-219b-4aca-8bb5-65e2e898e20b EC2RESCUE_OFFLINE_DEVICE Offline device name /dev/xvdf1
EC2RESCUE_OFFLINE_EBS_DEVICEOffline root volume EBS device /dev/sdf EC2RESCUE_OFFLINE_SYSTEM_ROOTOffline root volume mount point /mnt/mount
EC2RESCUE_PYTHON Python version python2.7
EC2RESCUE_REGION {{ global:REGION }} us-west-1
EC2RESCUE_S3_BUCKET {{ S3BucketName }} mybucket
EC2RESCUE_S3_PREFIX {{ S3Prefix }} myprefix/
EC2RESCUE_SOURCE_INSTANCE {{ InstanceId }} i-abcdefgh123456789
Document type Automation Owner Amazon Platforms
Linux, macOS, Windows Parameters
AWSSupport-StartEC2RescueWorkflow
• AMIPrefix Type: String
Default: AWSSupport-EC2Rescue
Description: (Optional) A prefix for the backup AMI name.
• AutomationAssumeRole Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.
• CreatePostEC2RescueBackup Type: String
Valid values: True | False Default: False
Description: (Optional) Set it to True to create an AMI of InstanceId after running the script, before starting it. The AMI will persist after the automation completes. It is your responsibility to secure access to the AMI, or to delete it.
• CreatePreEC2RescueBackup Type: String
Valid values: True | False Default: False
Description: (Optional) Set it to True to create an AMI of InstanceId before running the script. The AMI will persist after the automation completes. It is your responsibility to secure access to the AMI, or to delete it.
• EC2RescueInstanceType Type: String
Valid values: t2.small | t2.medium | t2.large Default: t2.small
Description: (Optional) The EC2 instance type for the EC2Rescue instance.
• InstanceId Type: String
Description: (Required) ID of your EC2 instance. IMPORTANT: AWS Systems Manager Automation stops this instance. Data stored in instance store volumes will be lost. The public IP address will change if you are not using an Elastic IP.
• OfflineScript Type: String
AWSSupport-StartEC2RescueWorkflow
• S3BucketName Type: String
Description: (Optional) S3 bucket name in your account where you want to upload the troubleshooting logs. Make sure the bucket policy does not grant unnecessary read/write permissions to parties that do not need access to the collected logs.
• S3Prefix Type: String
Default: AWSSupport-EC2Rescue
Description: (Optional) A prefix for the S3 logs.
• SubnetId Type: String
Default: SelectedInstanceSubnet
Description: (Optional) The subnet ID for the EC2Rescue instance. By default, the same subnet where the provided instance resides is used. IMPORTANT: If you provide a custom subnet, it must be in the same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
• UniqueId Type: String
Default: {{ automation:EXECUTION_ID }}
Description: (Optional) A unique identifier for the automation.
Required IAM permissions
The AutomationAssumeRole parameter requires the following actions to successfully use the runbook.
It is recommended the user who runs the automation have the AmazonSSMAutomationRole IAM managed policy attached. In addition to that policy, the user must have:
{
AWSSupport-StartEC2RescueWorkflow
1. aws:executeAwsApi - Describe the provided instance
2. aws:executeAwsApi - Describe the provided instance's root volume
3. aws:assertAwsResourceProperty - Check the root volume device type is EBS 4. aws:assertAwsResourceProperty - Check the root volume is not encrypted 5. aws:assertAwsResourceProperty - Check the provide subnet ID
a. (Use current instance subnet) - If *SubnetId = SelectedInstanceSubnet* then run
AWSSupport-StartEC2RescueWorkflow
b. (Create new VPC) - If *SubnetId = CreateNewVPC* then run aws:createStack to deploy the EC2Rescue CloudFormation stack
c. (Use custom subnet) - In all other cases:
aws:assertAwsResourceProperty - Check the provided subnet is in the same Availability Zone as the provided instance
aws:createStack - Deploy the EC2Rescue CloudFormation stack 6. aws:invokeLambdaFunction - Perform additional input validation
7. aws:executeAwsApi - Update the EC2Rescue CloudFormation stack to create the EC2Rescue helper instance
8. aws:waitForAwsResourceProperty - Wait for the EC2Rescue CloudFormation stack update to complete
9. aws:executeAwsApi - Describe the EC2Rescue CloudFormation stack output to obtain the EC2Rescue helper instance ID
10.aws:waitForAwsResourceProperty - Wait for the EC2Rescue helper instance to become a managed instance
11.aws:changeInstanceState - Stop the provided instance 12.aws:changeInstanceState - Stop the provided instance 13.aws:changeInstanceState - Force stop the provided instance
14.aws:assertAwsResourceProperty - Check the CreatePreEC2RescueBackup input value a. (Create pre-EC2Rescue backup) - If *CreatePreEC2RescueBackup = True*
b. aws:executeAwsApi - Create an AMI backup of the provided instance c. aws:createTags - Tag the AMI backup
15.aws:runCommand - Install EC2Rescue on the EC2Rescue helper instance 16.aws:executeAwsApi - Detach the root volume from the provided instance 17.aws:assertAwsResourceProperty - Check the provided instance platform
a. (Instance is Windows):
aws:executeAwsApi - Attach the root volume to the EC2Rescue helper instance as *xvdf*
aws:sleep - Sleep 10 seconds
aws:runCommand - Run the provided offline script in Powershell b. (Instance is Linux):
aws:executeAwsApi - Attach the root volume to the EC2Rescue helper instance as */dev/sdf*
aws:sleep - Sleep 10 seconds
aws:runCommand - Run the provided offline script in Bash 18.aws:changeInstanceState - Stop the EC2Rescue helper instance 19.aws:changeInstanceState - Force stop the EC2Rescue helper instance
20.aws:executeAwsApi - Detach the root volume from the EC2Rescue helper instance 21.aws:executeAwsApi - Attach the root volume back to the provided instance
22.aws:assertAwsResourceProperty - Check the CreatePostEC2RescueBackup input value a. (Create post-EC2Rescue backup) - If *CreatePostEC2RescueBackup = True*
b. aws:executeAwsApi - Create an AMI backup of the provided instance c. aws:createTags - Tag the AMI backup
23.aws:executeAwsApi - Restore the initial delete on termination state for the root volume of the provided instance