# Amazon EC2
AWS Systems Manager Automation provides predefined runbooks for Amazon Elastic Compute Cloud. Runbooks for Amazon Elastic Block Store are located in the [Amazon EBS](automation-ref-ebs.md) section of the Runbook Reference. For more information about runbooks, see [Working with runbooks](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-documents.html). For information about how to view runbook content, see [View runbook content](automation-runbook-reference.md#view-automation-json).
**Topics**
+ [`AWS-ASGEnterStandby`](automation-aws-asgenterstandby.md)
+ [`AWS-ASGExitStandby`](automation-aws-asgexitstandby.md)
+ [`AWS-CreateImage`](automation-aws-createimage.md)
+ [`AWS-DeleteImage`](automation-aws-deleteimage.md)
+ [`AWS-PatchAsgInstance`](automation-aws-patchasginstance.md)
+ [`AWS-PatchInstanceWithRollback`](automation-aws-patchinstancewithrollback.md)
+ [`AWS-QuarantineEC2Instance`](aws-quarantineec2instance.md)
+ [`AWS-ResizeInstance`](automation-aws-resizeinstance.md)
+ [`AWS-RestartEC2Instance`](automation-aws-restartec2instance.md)
+ [`AWS-SetupJupyter`](aws-setup-jupyter.md)
+ [`AWS-StartEC2Instance`](automation-aws-startec2instance.md)
+ [`AWS-StopEC2Instance`](automation-aws-stopec2instance.md)
+ [`AWS-TerminateEC2Instance`](automation-aws-terminateec2instance.md)
+ [`AWS-UpdateLinuxAmi`](automation-aws-updatelinuxami.md)
+ [`AWS-UpdateWindowsAmi`](automation-aws-updatewindowsami.md)
+ [`AWSConfigRemediation-EnableAutoScalingGroupELBHealthCheck`](automation-aws-enable-asg-health-check.md)
+ [`AWSConfigRemediation-EnforceEC2InstanceIMDSv2`](automation-aws-enforce-ec2-imdsv2.md)
+ [`AWSEC2-CloneInstanceAndUpgradeSQLServer`](automation-awsec2-CloneInstanceAndUpgradeSQLServer.md)
+ [`AWSEC2-CloneInstanceAndUpgradeWindows`](automation-awsec2-CloneInstanceAndUpgradeWindows.md)
+ [`AWSEC2-PatchLoadBalancerInstance`](automation-awsec2-patch-load-balancer-instance.md)
+ [`AWSEC2-SQLServerDBRestore`](automation-awsec2-sqlserverdbrestore.md)
+ [`AWSSupport-ActivateWindowsWithAmazonLicense`](automation-awssupport-activatewindowswithamazonlicense.md)
+ [`AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2`](automation-awssupport-analyzeawsendpointreachabilityfromec2.md)
+ [`AWSPremiumSupport-ChangeInstanceTypeIntelToAMD`](automation-aws-changeinstancetypeinteltoamd.md)
+ [`AWSSupport-CheckXenToNitroMigrationRequirements`](automation-awssupport-checkxentonitromigrationrequirements.md)
+ [`AWSSupport-CloneXenEC2InstanceAndMigrateToNitro`](automation-awssupport-clonexenec2instanceandmigratetonitro.md)
+ [`AWSSupport-CollectSAPHANALogs`](automation-awssupport-collectsaphanalogs.md)
+ [`AWSSupport-ConfigureEC2Metadata`](automation-awssupport-configureec2metadata.md)
+ [`AWSSupport-ContainEC2Instance`](automation-awssupport-containec2instance.md)
+ [`AWSSupport-CopyEC2Instance`](automation-awssupport-copyec2instance.md)
+ [`AWSPremiumSupport-DiagnoseDiskUsageOnLinux`](automation-awspremiumsupport-diagnosediskusageonlinux.md)
+ [`AWSSupport-EnableWindowsEC2SerialConsole`](automation-enable-windows-ec2-serial-console.md)
+ [`AWSPremiumSupport-ExtendVolumesOnWindows`](automation-awspremiumsupport-extendvolumesonwindows.md)
+ [`AWSSupport-ExecuteEC2Rescue`](automation-awssupport-executeec2rescue.md)
+ [`AWSSupport-ListEC2Resources`](automation-awssupport-listec2resources.md)
+ [`AWSSupport-ManageRDPSettings`](automation-awssupport-managerdpsettings.md)
+ [`AWSSupport-ManageWindowsService`](automation-awssupport-managewindowsservice.md)
+ [`AWSSupport-MigrateEC2ClassicToVPC`](automation-awssupport-migrate-ec2-classic-to-vpc.md)
+ [`AWSSupport-MigrateXenToNitroLinux`](automation-awssupport-migrate-xen-to-nitro.md)
+ [`AWSSupport-ResetAccess`](automation-awssupport-resetaccess.md)
+ [`AWSSupport-ResetLinuxUserPassword`](automation-awssupport-resetlinuxuserpassword.md)
+ [`AWSSupport-RunEC2RescueForWindowsTool`](automation-awssupport-runec2rescueforwindowstool.md)
+ [`AWSPremiumSupport-ResizeNitroInstance`](automation-aws-resizenitroinstance.md)
+ [`AWSSupport-ShareEncryptedAMIOrEBSSnapshot`](awssupport-share-encrypted-ami-or-ebs-snapshot.md)
+ [`AWSSupport-RestoreEC2InstanceFromSnapshot`](automation-awssupport-restoreec2instancefromsnapshot.md)
+ [`AWSSupport-SendLogBundleToS3Bucket`](automation-awssupport-sendlogbundletos3bucket.md)
+ [`AWSSupport-StartEC2RescueWorkflow`](automation-awssupport-startec2rescueworkflow.md)
+ [`AWSSupport-TroubleshootActiveDirectoryReplication`](automation-aws-troubleshootactivedirectoryreplication.md)
+ [`AWSPremiumSupport-TroubleshootEC2DiskUsage`](automation-awspremiumsupport-troubleshootEC2diskusage.md)
+ [`AWSSupport-TroubleshootEC2InstanceConnect`](automation-troubleshoot-ec2-instance-connect.md)
+ [`AWSSupport-TroubleshootLinuxMGNDRSAgentLogs`](automation-troublshoot-linux-mngdrs-agent-logs.md)
+ [`AWSSupport-TroubleshootRDP`](automation-awssupport-troubleshootrdp.md)
+ [`AWSSupport-TroubleshootSSH`](automation-awssupport-troubleshootssh.md)
+ [`AWSSupport-TroubleshootSUSERegistration`](automation-awssupport-troubleshoot-suse-registration.md)
+ [`AWSSupport-TroubleshootWindowsPerformance`](awssupport-troubleshoot-windows-performance.md)
+ [`AWSSupport-TroubleshootWindowsUpdate`](awssupport-troubleshoot-windows-update.md)
+ [`AWSSupport-UpgradeWindowsAWSDrivers`](automation-awssupport-upgradewindowsawsdrivers.md)
# `AWS-ASGEnterStandby`
**Description**
Change the standby state of an Amazon Elastic Compute Cloud (Amazon EC2) instance in an Auto Scaling group.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-ASGEnterStandby)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) ID of an Amazon EC2 instance for which you want to change the standby state within an Auto Scaling group.
+ LambdaRoleArn
Type: String
Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the actions on your behalf. If not specified a transient role will be created to run the Lambda function.
# `AWS-ASGExitStandby`
**Description**
Change the standby state of an Amazon Elastic Compute Cloud (Amazon EC2) instance in an Auto Scaling group.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-ASGExitStandby)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) ID of an EC2 instance for which you want to change the standby state within an Auto Scaling group.
+ LambdaRoleArn
Type: String
Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the actions on your behalf. If not specified a transient role will be created to run the Lambda function.
# `AWS-CreateImage`
**Description**
Create a new Amazon Machine Image (AMI) from an Amazon Elastic Compute Cloud (Amazon EC2) instance.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-CreateImage)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the EC2 instance.
+ NoReboot
Type: Boolean
Description: (Optional) Do not reboot the instance before creating the image.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateImage",
"ec2:DescribeImages"
],
"Resource": [
"*"
]
}
]
}
```
------
# `AWS-DeleteImage`
**Description**
Delete an Amazon Machine Image (AMI) and all associated snapshots.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-DeleteImage)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ ImageId
Type: String
Description: (Required) The ID of the AMI.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:DeleteSnapshot",
"Resource": "arn:aws:ec2:*:*:snapshot/*"
},
{
"Effect": "Allow",
"Action": "ec2:DescribeImages",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:DeregisterImage",
"Resource": "*"
}
]
}
```
------
# `AWS-PatchAsgInstance`
**Description**
Patch Amazon Elastic Compute Cloud (Amazon EC2) instances in an Auto Scaling group.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-PatchAsgInstance)
**Important**
This runbook applies an `AutoPatchInstanceInASG` tag to the target instance during execution. This tag prevents the runbook from executing twice on the same instance simultaneously — it is not a patch compliance indicator. If the patching step fails, the tag value might still be set to `Completed` even though the runbook execution status reports `Failed`.
To verify patch compliance on the instance, use [DescribeInstancePatchStates](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstancePatchStates.html) or [ListComplianceItems](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_ListComplianceItems.html) instead.
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) ID of the instance to patch. Don't specify an instance ID that is configured to run during a maintenance window.
+ LambdaRoleArn
Type: String
Description: (Optional) The ARN of the role that allows the Lambda created by Automation to perform the actions on your behalf. If not specified, a transient role will be created to run the Lambda function.
+ WaitForInstance
Type: String
Default: PT2M
Description: (Optional) Duration that the Automation should sleep to allow the instance to come back into service.
+ WaitForReboot
Type: String
Default: PT5M
Description: (Optional) Duration that the Automation should sleep to allow a patched instance to reboot.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:GetCommandInvocation`
+ `ssm:GetParameter`
+ `ssm:SendCommand`
+ `cloudformation:CreateStack`
+ `cloudformation:DeleteStack`
+ `cloudformation:DescribeStacks`
+ `ec2:CreateTags`
+ `ec2:DescribeInstances`
+ `ec2:RunInstances`
+ `iam:AttachRolePolicy`
+ `iam:CreateRole`
+ `iam:DeleteRole`
+ `iam:DeleteRolePolicy`
+ `iam:DetachRolePolicy`
+ `iam:GetRole`
+ `iam:PassRole`
+ `iam:PutRolePolicy`
+ `lambda:CreateFunction`
+ `lambda:DeleteFunction`
+ `lambda:GetFunction`
+ `lambda:InvokeFunction`
# `AWS-PatchInstanceWithRollback`
**Description**
Brings an EC2 instance into compliance with the applicable patch baseline. Rolls back root volume on failure.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-PatchInstanceWithRollback)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) EC2 InstanceId to which we apply the patch-baseline.
+ LambdaAssumeRole
Type: String
Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the actions on your behalf. If not specified a transient role will be created to run the Lambda function.
+ ReportS3Bucket
Type: String
Description: (Optional) Amazon S3 Bucket destination for the Compliance Report generated during process.
**Document Steps**
****
| Step number | Step name | Automation action |
| --- | --- | --- |
| 1 | createDocumentStack | `aws:createStack` |
| 2 | IdentifyRootVolume | `aws:invokeLambdaFunction` |
| 3 | PrePatchSnapshot | `aws:executeAutomation` |
| 4 | installMissingUpdates | `aws:runCommand` |
| 5 | SleepThruInstallation | `aws:invokeLambdaFunction` |
| 6 | CheckCompliance | `aws:invokeLambdaFunction` |
| 7 | SaveComplianceReportToS3 | `aws:invokeLambdaFunction` |
| 8 | ReportSuccessOrFailure | `aws:invokeLambdaFunction` |
| 9 | RestoreFromSnapshot | `aws:invokeLambdaFunction` |
| 10 | DeleteSnapshot | `aws:invokeLambdaFunction` |
| 11 | deleteCloudFormationTemplate | `aws:deleteStack` |
**Outputs**
IdentifyRootVolume.Payload
PrePatchSnapshot.Output
SaveComplianceReportToS3.Payload
RestoreFromSnapshot.Payload
CheckCompliance.Payload
# `AWS-QuarantineEC2Instance`
**Description**
With the `AWS-QuarantineEC2Instance` runbook, you can assign a security group to an Amazon Elastic Compute Cloud (Amazon EC2) instance that doesn't allow any inbound or outbound traffic.
**Important**
Changes to the RDP settings should be carefully reviewed before running this runbook.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-QuarantineEC2Instance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the managed instance to manage the RDP settings of.
+ IsolationSecurityGroup
Type: String
Description: (Required) The name of the security group that you want to assign to the instance to prevent inbound or outbound traffic.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `autoscaling:DescribeAutoScalingInstances`
+ `autoscaling:DetachInstances`
+ `ec2:CreateSecurityGroup`
+ `ec2:CreateSnapshot`
+ `ec2:DescribeInstances`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeSnapshots`
+ `ec2:ModifyInstanceAttribute`
+ `ec2:RevokeSecurityGroupEgress`
+ `ec2:RevokeSecurityGroupIngress`
**Document Steps**
+ `aws:executeAwsApi` - Gathers details about the instance.
+ `aws:executeScript` - Verifies the instance isn't part of an Auto Scaling group.
+ `aws:executeAwsApi` - Creates a snapshot of the root volume attached to the instance.
+ `aws:waitForAwsResourceProperty` - Waits for the snapshot state to be `completed`.
+ `aws:executeAwsApi` - Assigns the security group specified in the `IsolationSecurityGroup` parameter to your instance.
**Outputs**
`GetEC2InstanceResources.RevokedSecurityGroupsIds`
`GetEC2InstanceResources.RevokedSecurityGroupsNames`
`createSnapshot.SnapId`
# `AWS-ResizeInstance`
**Description**
Change the instance type of an Amazon Elastic Compute Cloud (Amazon EC2) instance.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-ResizeInstance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the instance.
+ InstanceType
Type: String
Description: (Required) The instance type.
# `AWS-RestartEC2Instance`
**Description**
Restart one or more Amazon Elastic Compute Cloud (Amazon EC2) instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-RestartEC2Instance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: StringList
Description: (Required) The IDs of the Amazon EC2 instances to restart.
# `AWS-SetupJupyter`
**Description**
The `AWS-SetupJupyter` runbook helps you set up Jupyter Notebook on an Amazon Elastic Compute Cloud (Amazon EC2) instance. You can either specify an existing instance, or provide an Amazon Machine Image (AMI) ID for the automation to launch and set up a new instance. Before you begin, you must create a `SecureString` parameter in Parameter Store to use as the password for Jupyter Notebook. Parameter Store is a tool in AWS Systems Manager. For information about creating parameters, see [Creating parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-su-create.html) in the *AWS Systems Manager User Guide*.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-SetupJupyter)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
+ AmiId
Type: String
Description: (Optional) The ID of the AMI that you want to use to launch a new instance and set up Jupyter Notebook.
+ InstanceId
Type: String
Description: (Required) The ID of the instance that you want to set up Jupyter Notebook on.
+ InstanceType
Type: String
Default: t3.medium
Description: (Optional) If you're launching a new instance to set up Jupyter Notebook, specify the instance type that you want to use.
+ JupyterPasswordSSMKey
Type: String
Description: (Required) The name of the `SecureString` parameter in Parameter Store that you want to use as the password for Jupyter Notebook.
+ KeyPairName
Type: String
Description: (Optional) The key pair that you want to associate with the newly launched instance.
+ RemoteAccessCidr
Type: String
Default: 0.0.0.0/0
Description: (Optional) The CIDR range that you want to allow SSH traffic from.
+ RoleName
Type: String
Default: SSMManagedInstanceProfileRole
Description: (Optional) The name of the instance profile for the newly launched instance.
+ StackName
Type: String
Default: CreateManagedInstanceStack\$1\$1automation:EXECUTION\$1ID\$1\$1
Description: (Optional) The CloudFormation stack name that you want the automation to use.
+ SubnetId
Type: String
Default: Default
Description: (Optional) The subnet that you want to launch the new instance to use.
+ VpcId
Type: String
Default: Default
Description: (Optional) The ID of the virtual private cloud (VPC) that you want to launch the new instance in to.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:GetAutomationExecution`
+ `ssm:GetCommandInvocation`
+ `ssm:GetParameter`
+ `ssm:SendCommand`
+ `ssm:StartAutomationExecution`
+ `cloudformation:CreateStack`
+ `cloudformation:DeleteStack`
+ `cloudformation:DescribeStacks`
+ `ec2:DescribeInstances`
+ `ec2:DescribeKeyPairs`
+ `ec2:RunInstances`
+ `iam:AttachRolePolicy`
+ `iam:CreateRole`
+ `iam:DeleteRole`
+ `iam:DeleteRolePolicy`
+ `iam:DetachRolePolicy`
+ `iam:GetRole`
+ `iam:PassRole`
+ `iam:PutRolePolicy`
+ `lambda:CreateFunction`
+ `lambda:DeleteFunction`
+ `lambda:GetFunction`
+ `lambda:InvokeFunction`
**Document Steps**
+ `aws:executeScript` - Sets up Jupyter Notebook on the instance you specify, or on a newly launched instance, using the values that you specify for the runbook input parameters.
# `AWS-StartEC2Instance`
**Description**
Start one or more Amazon Elastic Compute Cloud (Amazon EC2) instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-StartEC2Instance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: StringList
Description: (Required) EC2 instances to start.
# `AWS-StopEC2Instance`
**Description**
Stops one or more Amazon Elastic Compute Cloud (Amazon EC2) instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-StopEC2Instance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: StringList
Description: (Required) EC2 instances to stop.
# `AWS-TerminateEC2Instance`
**Description**
Terminate one or more Amazon Elastic Compute Cloud (Amazon EC2) instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-TerminateEC2Instance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: StringList
Description: (Required) IDs of one or more EC2 instances to terminate.
# `AWS-UpdateLinuxAmi`
**Description**
Update an Amazon Machine Image (AMI) with Linux distribution packages and Amazon software.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-UpdateLinuxAmi)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
Allowed Pattern: `^$|^arn:aws[a-z0-9-]*:iam::(\d{12}|\{\{global:ACCOUNT_ID\}\}):role/[\w/.@+=,-]{1,1017}$`
+ Must be a valid IAM role ARN or an empty string. System variable `{{global:ACCOUNT_ID}}` can be used in place of the AWS Account ID in the arn.
+ ExcludePackages
Type: String
Default: none
Description: (Optional) Names of packages to hold back from updates, under all conditions. By default ("none"), no package is excluded.
Allowed Pattern: `^(none|[a-zA-Z0-9\s,._+:=<>()\[\]/*-]+)$`
+ Must be "none" OR a comma-separated list of items consisting of letters, numbers, spaces, and the following characters: `, . _ + : = < > ( ) [ ] / * -`
+ IamInstanceProfileName
Type: String
Default: ManagedInstanceProfile
Description: (Required) The instance profile that enables Systems Manager to manage the instance.
Allowed Pattern: `^[\w+=,.@-]{1,128}$`
+ Must be between 1 and 128 characters and contain only letters, numbers, and these characters: `+ = , . @ - _`
+ IncludePackages
Type: String
Default: all
Description: (Optional) Only update these named packages. By default ("all"), all available updates are applied.
Allowed Pattern: `^(all|[a-zA-Z0-9\s,._+:=<>()\[\]/*-]+)$`
+ Must be "all" OR a comma-separated list of items consisting of letters, numbers, spaces, and the following characters: `, . _ + : = < > ( ) [ ] / * -`
+ InstanceType
Type: String
Default: t2.micro
Description: (Optional) Type of instance to launch as the workspace host. Instance types vary by Region.
Allowed Pattern: `^[a-z0-9]+(-[a-z0-9]+)*\.[a-z0-9]+$`
+ Must be in the format prefix.suffix where both parts contain lowercase letters and numbers, and the prefix may include hyphens
+ MetadataOptions
Type: StringMap
Default: \$1"HttpEndpoint": "enabled", "HttpTokens": "optional"\$1
Description: (Optional) The metadata options for the instance. For more information, see [InstanceMetadataOptionsRequest](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InstanceMetadataOptionsRequest.html).
Allowed Pattern: `^\{[^<>\$;|&\\]*\}$`
+ Must be wrapped in curly braces \$1 \$1 and cannot contain these characters: `< > $ ; | & \`
+ PostUpdateScript
Type: String
Default: none
Description: (Optional) URL of a script to run after package updates are applied. Default ("none") is to not run a script.
Allowed Pattern: `^(none|https?://[\w\-._~:/?#\[\]@!$&'()*+,;=%]+)$`
+ Must be "none" OR a valid HTTP/HTTPS URL
+ PreUpdateScript
Type: String
Default: none
Description: (Optional) URL of a script to run before updates are applied. Default ("none") is to not run a script.
Allowed Pattern: `^(none|https?://[\w\-._~:/?#\[\]@!$&'()*+,;=%]+)$`
+ Must be "none" OR a valid HTTP/HTTPS URL
+ SecurityGroupIds
Type: String
Description: (Required) A comma separated list of the IDs of the security groups you want to apply to the AMI.
Allowed Pattern: `^sg-[a-z0-9]{8,17}$`
+ Must start with "sg-" followed by 8-17 lowercase letters or numbers
+ SourceAmiId
Type: String
Description: (Required) The source Amazon Machine Image ID.
Allowed Pattern: `^ami-[a-z0-9]{8,17}$`
+ Must start with "ami-" followed by 8-17 lowercase letters or numbers
+ SubnetId
Type: String
Description: (Optional) The ID of the subnet you want to launch the instance into. If you have deleted your default VPC, this parameter is required.
Allowed Pattern: `^$|^subnet-[a-z0-9]{8,17}$`
+ Must be empty OR start with "subnet-" followed by 8-17 lowercase letters or numbers
+ TargetAmiName
Type: String
Default: UpdateLinuxAmi\$1from\$1\$1\$1SourceAmiId\$1\$1\$1on\$1\$1\$1global:DATE\$1TIME\$1\$1
Description: (Optional) The name of the new AMI that will be created. Default is a system-generated string including the source AMI id, and the creation time and date.
Allowed Pattern: `^[a-zA-Z0-9()\[\]\{\} ./'@_:-]{3,128}$`
+ Must be between 3 and 128 characters and contain only letters, numbers, spaces, and these characters: `( ) [ ] { } . / ' @ _ : -`
# `AWS-UpdateWindowsAmi`
**Description**
Update a Microsoft Windows Amazon Machine Image (AMI). By default, this runbook installs all Windows updates, Amazon software, and Amazon drivers. It then runs Sysprep to create a new AMI. Supports Windows Server 2008 R2 through Windows Server 2022.
**Important**
This runbook does not support Windows Server 2025 and later versions, as AWS Paravirtual drivers are not compatible with these versions. For more information, see [Paravirtual drivers for Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/xen-drivers-overview.html).
**Important**
If your instances connect to AWS Systems Manager using VPC endpoints, this runbook will fail unless used in the us-east-1 Region. Instances must have TLS 1.2 enabled to use this runbook.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWS-UpdateWindowsAmi)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
+ 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.
+ Categories
Type: String
Description: (Optional) Specify one or more update categories. You can filter categories using comma-separated values. Options: Application, Connectors, CriticalUpdates, DefinitionUpdates, DeveloperKits, Drivers, FeaturePacks, Guidance, Microsoft, SecurityUpdates, ServicePacks, Tools, UpdateRollups, Updates. Valid formats include a single entry, for example: CriticalUpdates. Or you can specify a comma separated list: CriticalUpdates,SecurityUpdates. NOTE: There cannot be any spaces around the commas.
+ ExcludeKbs
Type: String
Description: (Optional) Specify one or more Microsoft Knowledge Base (KB) article IDs to exclude. You can exclude multiple IDs using comma-separated values. Valid formats: KB9876543 or 9876543.
+ IamInstanceProfileName
Type: String
Default: ManagedInstanceProfile
Description: (Required) The name of the role that enables Systems Manager to manage the instance.
+ IncludeKbs
Type: String
Description: (Optional) Specify one or more Microsoft Knowledge Base (KB) article IDs to include. You can install multiple IDs using comma-separated values. Valid formats: KB9876543 or 9876543.
+ InstanceType
Type: String
Default: t2.medium
Description: (Optional) Type of instance to launch as the workspace host. Instance types vary by region. Default is t2.medium.
+ MetadataOptions
Type: StringMap
Default: \$1"HttpEndpoint": "enabled", "HttpTokens": "optional"\$1
Description: (Optional) The metadata options for the instance. For more information, see [InstanceMetadataOptionsRequest](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InstanceMetadataOptionsRequest.html).
+ PostUpdateScript
Type: String
Description: (Optional) A script provided as a string. It will run after installing OS updates.
+ PreUpdateScript
Type: String
Description: (Optional) A script provided as a string. It will run prior to installing OS updates.
+ PublishedDateAfter
Type: String
Description: (Optional) Specify the date that the updates should be published after. For example, if 01/01/2017 is specified, any updates that were found during the Windows Update search that have been published on or after 01/01/2017 will be returned.
+ PublishedDateBefore
Type: String
Description: (Optional) Specify the date that the updates should be published before. For example, if 01/01/2017 is specified, any updates that were found during the Windows Update search that have been published on or before 01/01/2017 will be returned.
+ PublishedDaysOld
Type: String
Description: (Optional) Specify the amount of days old the updates must be from the published date. For example, if 10 is specified, any updates that were found during the Windows Update search that have been published 10 or more days ago will be returned.
+ SecurityGroupIds
Type: String
Description: (Required) A comma separated list of the IDs of the security groups you want to apply to the AMI.
+ SeverityLevels
Type: String
Description: (Optional) Specify one or more MSRC severity levels associated with an update. You can filter severity levels using comma-separated values. By default patches for all security levels are selected. If value supplied, the update list is filtered by those values. Options: Critical, Important, Low, Moderate or Unspecified. Valid formats include a single entry, for example: Critical. Or, you can specify a comma separated list: Critical,Important,Low.
+ SourceAmiId
Type: String
Description: (Required) The source AMI ID.
+ SubnetId
Type: String
Description: (Optional) The ID of the subnet you want to launch the instance into. If you have deleted your default VPC, this parameter is required.
+ TargetAmiName
Type: String
Default: UpdateWindowsAmi\$1from\$1\$1\$1SourceAmiId\$1\$1\$1on\$1\$1\$1global:DATE\$1TIME\$1\$1
Description: (Optional) The name of the new AMI that will be created. Default is a system-generated string including the source AMI id, and the creation time and date.
# `AWSConfigRemediation-EnableAutoScalingGroupELBHealthCheck`
**Description**
The `AWSConfigRemediation-EnableAutoScalingGroupELBHealthCheck` runbook enables health checks for the Amazon EC2 Auto Scaling (Auto Scaling) group you specify.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSConfigRemediation-EnableAutoScalingGroupELBHealthCheck)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Required) 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.
+ AutoScalingGroupARN
Type: String
Description: (Required) The Amazon Resource Name (ARN) of the auto scaling group that you want to enable health checks on.
+ HealthCheckGracePeriod
Type: Integer
Default: 300
Description: (Optional) The amount of time, in seconds, that Auto Scaling waits before checking the health status of an Amazon Elastic Compute Cloud (Amazon EC2) instance that has come into service.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ec2:DescribeAutoScalingGroups`
+ `ec2:UpdateAutoScalingGroup`
**Document Steps**
+ `aws:executeScript` - Enables health checks on the Auto Scaling group you specify in the `AutoScalingGroupARN` parameter.
# `AWSConfigRemediation-EnforceEC2InstanceIMDSv2`
**Description**
The `AWSConfigRemediation-EnforceEC2InstanceIMDSv2` runbook requires the Amazon Elastic Compute Cloud (Amazon EC2) instance you specify to use Instance Metadata Service Version 2 (IMDSv2).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSConfigRemediation-EnforceEC2InstanceIMDSv2)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instance you want to require to use IMDSv2.
+ AutomationAssumeRole
Type: String
Description: (Required) 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.
+ HttpPutResponseHopLimit
Type: Integer
Description: (Optional) The Hop response limit from the IMDS service back to the requester. Set to 2 or greater for EC2 instances hosting containers. Set to 0 to not change (Default).
Allowed pattern: `^([1-5]?\d|6[0-4])$`
Default: 0
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ec2:DescribeInstances`
+ `ec2:ModifyInstanceMetadataOptions`
**Document Steps**
+ `aws:executeScript` - Sets the `HttpTokens` option to `required` on the Amazon EC2 instance you specify in the `InstanceId` parameter.
+ `aws:assertAwsResourceProperty` - Verifies IMDSv2 is required on the Amazon EC2 instance.
# `AWSEC2-CloneInstanceAndUpgradeSQLServer`
**Description**
Create an AMI from an EC2 instance for Windows Server running SQL Server 2008 or later, and then upgrade the AMI to a later version of SQL Server. Only English versions of SQL Server are supported.
The following upgrade paths are supported:
+ SQL Server 2008 to SQL Server 2017, 2016, or 2014
+ SQL Server 2008 R2 to SQL Server 2017, 2016, or 2014
+ SQL Server 2012 to SQL Server 2019, 2017, 2016, or 2014
+ SQL Server 2014 to SQL Server 2019, 2017, or 2016
+ SQL Server 2016 to SQL Server 2019 or 2017
If you are using an earlier version of Windows Server that is incompatible with SQL Server 2019, the automation document must upgrade your Windows Server version to 2016.
The upgrade is a multi-step process that can take 2 hours to complete. The automation creates the AMI from the instance, and then launches a temporary instance from the new AMI in the specified `SubnetID`. The security groups associated with your original instance are applied to the temporary instance. The automation then performs an in-place upgrade to the `TargetSQLVersion` on the temporary instance. After the upgrade, the automation creates a new AMI from the temporary instance and then terminates the temporary instance.
You can test application functionality by launching the new AMI in your VPC. After you finish testing, and before you perform another upgrade, schedule application downtime before completely switching over to the upgraded instance.
**Note**
If you want to modify the computer name of the EC2 instance launched from the new AMI , see [Rename a Computer that Hosts a Stand-Alone Instance of SQL Server](https://docs.microsoft.com/en-us/sql/database-engine/install-windows/rename-a-computer-that-hosts-a-stand-alone-instance-of-sql-server?view=sql-server-2017).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSEC2-CloneInstanceAndUpgradeSQLServer)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
**Prerequisites**
+ TLS version 1.2.
+ Only English versions of SQL Server are supported.
+ The EC2 instance must use a version of Windows Server that is Windows Server 2008 R2 (or later) and SQL Server 2008 (or later).
+ Verify that SSM Agent is installed on your instance. For more information, see [Installing and configuring SSM Agent on EC2 instances for Windows Server](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-win.html).
+ Configure the instance to use an AWS Identity and Access Management (IAM) instance profile role. For more information, see [Create an IAM instance profile for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html).
+ Verify that the instance has 20 GB of free disk space in the instance boot disk.
+ For instances that use a Bring Your Own License (BYOL) SQL Server version, the following additional prerequisites apply:
+ Provide an EBS snapshot ID that includes the target SQL Server installation media. To do this:
1. Verify that the EC2 instance is running Windows Server 2008 R2 or later.
1. Create a 6 GB EBS volume in the same Availability Zone where the instance is running. Attach the volume to the instance. Mount it, for example, as drive D.
1. Right-click the ISO and mount it to an instance as, for example, drive E.
1. Copy the content of the ISO from drive E:\$1 to drive D:\$1
1. Create an EBS snapshot of the 6 GB volume created in step 2.
**Limitations**
+ The upgrade can be performed on only a SQL Server using Windows authentication.
+ Verify that no security patch updates are pending on the instances. Open **Control Panel**, then choose **Check for updates**.
+ SQL Server deployments in HA and mirroring mode are not supported.
**Parameters**
+ IamInstanceProfile
Type: String
Description: (Required) The IAM instance profile.
+ InstanceId
Type: String
Description: (Required) The instance running Windows Server 2008 R2 (or later) and SQL Server 2008 (or later).
+ KeepPreUpgradeImageBackUp
Type: String
Description: (Optional) If set to `true`, the automation doesn't delete the AMI created from the instance before the upgrade. If set to `true`, then you must delete the AMI. By default, the AMI is deleted.
+ SubnetId
Type: String
Description: (Required) Provide a subnet for the upgrade process. Verify that the subnet has outbound connectivity to AWS services, Amazon S3, and Microsoft (to download patches).
+ SQLServerSnapshotId
Type: String
Description: (Conditional) Snapshot ID for target SQL Server installation media. This parameter is required for instances that use a BYOL SQL Server version. This parameter is optional for SQL Server license-included instances (instances launched using an AWS provided Amazon Machine Image for Windows Server with Microsoft SQL Server).
+ RebootInstanceBeforeTakingImage
Type: String
Description: (Optional) If set to `true`, the automation reboots the instance before creating a pre-upgrade AMI. By default, the automation doesn't reboot before upgrade.
+ TargetSQLVersion
Type: String
Description: (Optional) Select the target SQL Server version.
Possible targets:
+ SQL Server 2019
+ SQL Server 2017
+ SQL Server 2016
+ SQL Server 2014
Default target: SQL Server 2016
**Outputs**
AMIId: The ID of the AMI created from the instance that was upgraded to a later version of SQL Server.
# `AWSEC2-CloneInstanceAndUpgradeWindows`
**Description**
Create an Amazon Machine Image (AMI) from a Windows Server 2008 R2, 2012 R2, 2016, 2019, or 2022 instance, and then upgrade the AMI to Windows Server 2016, 2019, 2022, or 2025. The supported upgrade paths are as follows.
+ Windows Server 2008 R2 to Windows Server 2016.
+ Windows Server 2012 R2 to Windows Server 2016.
+ Windows Server 2012 R2 to Windows Server 2019.
+ Windows Server 2012 R2 to Windows Server 2022.
+ Windows Server 2016 to Windows Server 2019.
+ Windows Server 2016 to Windows Server 2022.
+ Windows Server 2016 to Windows Server 2025.
+ Windows Server 2019 to Windows Server 2022.
+ Windows Server 2019 to Windows Server 2025.
+ Windows Server 2022 to Windows Server 2025.
The upgrade operation is a multi-step process that can take 2 hours to complete. We recommend performing an operating system upgrade on instances with at least 2 vCPUs and 4GB of RAM. The automation creates an AMI from the instance and then launches a temporary instance from the newly created AMI in the `SubnetId` that you specify. The security groups associated with your original instance are applied to the temporary instance. The automation then performs an in-place upgrade to the `TargetWindowsVersion` on the temporary instance. To upgrade your Windows Server 2008 R2 instance to Windows Server 2016, 2019, or 2022, an in-place upgrade is performed twice because directly upgrading Windows Server 2008 R2 to Windows Server 2016, 2019, or 2022 is not supported. The automation also updates or installs the AWS drivers required by the temporary instance. After the upgrade, the automation creates a new AMI from the temporary instance and then terminates the temporary instance.
You can test application functionality by launching a test instance from the upgraded AMI in your Amazon Virtual Private Cloud (Amazon VPC). After you finish testing, and before you perform another upgrade, schedule application downtime before completely switching over to the upgraded AMI.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSEC2-CloneInstanceAndUpgradeWindows)
**Document Type**
Automation
**Owner**
Amazon
**Platforms**
Windows Server 2008 R2, 2012 R2, 2016, 2019, or 2022 Standard and Datacenter editions
**Prerequisites**
+ TLS version 1.2.
+ Verify that SSM Agent is installed on your instance. For more information, see [Installing and configuring SSM Agent on EC2 instances for Windows Server](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-win.html).
+ Windows PowerShell 3.0 or later must be installed on your instance.
+ For instances that are joined to a Microsoft Active Directory domain, we recommend specifying a `SubnetId` that does not have connectivity to your domain controllers to help avoid hostname conflicts.
+ The instance subnet must have outbound connectivity to the internet, which provides access to AWS services such as Amazon S3 and access to download patches from Microsoft. This requirement is met if either the subnet is a public subnet and the instance has a public IP address, or if the subnet is a private subnet with a route that sends internet traffic to a public NAT device.
+ This Automation works only with Windows Server 2008 R2, 2012 R2, 2016, 2019, and 2022 instances.
+ Configure the Windows Server instance with an AWS Identity and Access Management (IAM) instance profile that provides the requisite permissions for Systems Manager. For more information, see [Create an IAM instance profile for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html).
+ Verify that the instance has 20 GB of free disk space in the boot disk.
+ If the instance does not use an AWS-provided Windows license, then specify an Amazon EBS snapshot ID that includes Windows Server 2012 R2 installation media. To do this:
+ Verify that the EC2 instance is running Windows Server 2012 or later.
+ Create a 6 GB EBS volume in the same Availability Zone where the instance is running. Attach the volume to the instance. Mount it, for example, as drive D.
+ Right-click the ISO and mount it to an instance as, for example, drive E.
+ Copy the content of the ISO from drive E:\$1 to drive D:\$1
+ Create an EBS snapshot of the 6 GB volume created in step 2 above.
+ For Windows Server 2025 upgrades, the source instance must be [Nitro-based](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#instance-hypervisor-type).
**Limitations**
This Automation doesn't support upgrading Windows domain controllers, clusters, or Windows desktop operating systems. This Automation also doesn't support EC2 instances for Windows Server with the following roles installed.
+ Remote Desktop Session Host (RDSH)
+ Remote Desktop Connection Broker (RDCB)
+ Remote Desktop Virtualization Host (RDVH)
+ Remote Desktop Web Access (RDWA)
**Parameters**
+ AlternativeKeyPairName
Type: String
Description: (Optional) The name of an alternative key pair to use during the upgrade process. This is useful in situations where the key pair assigned to the original instance is unavailable. If the original instance was not assigned a key pair, you must specify a value for this parameter.
+ BYOLWindowsMediaSnapshotId
Type: String
Description: (Optional) The ID of the Amazon EBS snapshot to copy that includes Windows Server 2012R2 installation media. Required only if you are upgrading a BYOL instance.
+ IamInstanceProfile
Type: String
Description: (Required) The name of the IAM instance profile that enables Systems Manager to manage the instance.
+ InstanceId
Type: String
Description: (Required) The EC2 instance running Windows Server 2008 R2, 2012 R2, 2016, 2019, or 2022.
+ KeepPreUpgradeImageBackUp
Type: String
Description: (Optional) If set True, the Automation doesn't delete the AMI created from the EC2 instance before the upgrade. If set to True, then you must delete the AMI. By default, the AMI is deleted.
+ SubnetId
Type: String
Description: (Required) This is the subnet for the upgrade process and where your source EC2 instance resides. Verify that the subnet has outbound connectivity to AWS services, Amazon S3, and Microsoft (to download patches).
+ TargetWindowsVersion
Type: String
Description: (Required) Select the target Windows version.
Default: 2025
+ RebootInstanceBeforeTakingImage
Type: String
Description: (Optional) If set True, the Automation reboots the instance before creating a pre-upgrade AMI. By default, the Automation doesn't reboot before upgrade.
# `AWSEC2-PatchLoadBalancerInstance`
**Description**
Upgrade and patch minor version of an Amazon EC2 instance (Windows or Linux) attached to any load balancer (classic, ALB, or NLB). The default connection draining time is applied before the instance is patched. You can override the wait time by entering your custom draining time in minutes (`1`-`59`) for the **ConnectionDrainTime** parameter.
The automation workflow is as follows:
1. The load balancer or target group to which the instance is attached is determined, and the instance is verified as healthy.
1. The instance is removed from the load balancer or target group.
1. The automation waits for the period of time specified for the connection draining time.
1. The [AWS-RunPatchBaseline](https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-manager-about-aws-runpatchbaseline.html) automation is called to patch the instance.
1. The instance is reattached to the load balancer or target group.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSEC2-PatchLoadBalancerInstance)
**Document Type**
Automation
**Owner**
Amazon
**Prerequisites**
+ Verify that SSM Agent is installed on your instance. For more information, see [Working with SSM Agent on EC2 instances for Windows Server](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-win.html).
**Parameters**
+ **InstanceId**
Type: String
Description: (Required) ID of the instance to patch that is associated with a load balancer (classic, ALB, or NLB).
+ **ConnectionDrainTime**
Type: String
Description: (Optional) The connection draining time of the load balancer, in minutes (`1`-`59`).
+ **S3BucketLog**
Type: String
Description: (Optional) The name of the Amazon S3 bucket to use to store the command output responses. You can specify a bucket that you own or a bucket that is shared with you. If you provide this parameter, you must also provide ** runCommandAssumeRole**.
+ **runCommandAssumeRole**
Type: String
Description: (Optional) The ARN of the IAM role to use to run the command on the instance. The role must have a trust relationship with the `ssm.amazonaws.com` service principal, it must have the **AmazonSSMManagedInstanceCore** policy attached, and it must have write permissions for the Amazon S3 bucket specified for **S3BucketLog**.
# `AWSEC2-SQLServerDBRestore`
**Description**
The `AWSEC2-SQLServerDBRestore` runbook restores Microsoft SQL Server database backups stored in Amazon S3 to SQL Server 2017 running on an Amazon Elastic Compute Cloud (EC2) Linux instance. You may provide your own EC2 instance running SQL Server 2017 Linux. If an EC2 instance is not provided, the automation launches and configures a new Ubuntu 16.04 EC2 instance with SQL Server 2017. The automation supports restoring full, differential, and transactional log backups. This automation accepts multiple database backup files and automatically restores the most recent valid backup of each database in the files provided.
To automate both backup and restore of an on-premises SQL Server database to an EC2 instance running SQL Server 2017 Linux, you can use the AWS-signed PowerShell script [https://awsec2-server-upgrade-prod.s3.us-west-1.amazonaws.com/MigrateSQLServerToEC2Linux.ps1](https://awsec2-server-upgrade-prod.s3.us-west-1.amazonaws.com/MigrateSQLServerToEC2Linux.ps1).
**Important**
This runbook resets the SQL Server server administrator (SA) user password every time the automation runs. After the automation is complete, you must set your own SA user password again before you connect to the SQL Server instance.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSEC2-SQLServerDBRestore)
**Document Type**
Automation
**Owner**
Amazon
**Platforms**
Linux
## Prerequisites
To run this automation, you must meet the following prerequisites:
+ The IAM user or role that runs this automation must have an inline policy attached with the permissions outlined in [Required IAM permissions](#sql-server-db-restore-policy).
+ If you provide your own EC2 instance:
+ The EC2 instance that you provide must be a Linux instance running Microsoft SQL Server 2017.
+ The EC2 instance that you provide must be configured with an AWS Identity and Access Management (IAM) instance profile that has the `AmazonSSMManagedInstanceCore` managed policy attached. For more information, see [Create an IAM instance profile for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html).
+ The SSM Agent must be installed on your EC2 instance. For more information, see [Installing and configuring SSM Agent on EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-agent.html).
+ The EC2 instance must have enough free disk space to download and restore the SQL Server backups.
## Limitations
This automation does not support restoring to SQL Server running on EC2 instances for Windows Server. This automation only restores database backups that are compatible with SQL Server Linux 2017. For more information, see [Editions and Supported Features of SQL Server 2017 on Linux](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-editions-and-components-2017?view=sql-server-2017).
## Parameters
This automation has the following parameters:
+ **DatabaseNames**
Type: String
Description: (Optional) Comma-separated list of the names of databases to restore.
+ **DataDirectorySize**
Type: String
Description: (Optional) Desired volume size (GiB) of the SQL Server Data directory for the new EC2 instance.
Default value: 100
+ **KeyPair**
Type: String
Description: (Optional) Key pair to use when creating the new EC2 instance.
+ **IamInstanceProfileName**
Type: String
Description: (Optional) The IAM instance profile to attach to the new EC2 instance. The IAM instance profile must have the `AmazonSSMManagedInstanceCore` managed policy attached.
+ **InstanceId**
Type: String
Description: (Optional) The instance running SQL Server 2017 on Linux. If no InstanceId is provided, the automation launches a new EC2 instance using the InstanceType and SQLServerEdition provided.
+ **InstanceType**
Type: String
Description: (Optional) The instance type of the EC2 instance to be launched.
+ **IsS3PresignedUrl**
Type: String
Description: (Optional) If S3Input is a pre-signed S3 URL, indicate `yes`.
Default value: no
Valid values: yes \$1 no
+ **LogDirectorySize**
Type: String
Description: (Optional) Desired volume size (GiB) of the SQL Server Log directory for the new EC2 instance.
Default value: 100
+ **S3Input**
Type: String
Description: (Required) S3 bucket name, comma-separated list of S3 object keys, or comma-separated list of pre-signed S3 URLs containing the SQL backup files to be restored.
+ **SQLServerEdition**
Type: String
Description: (Optional) The edition of SQL Server 2017 to be installed on the newly created EC2 instance.
Valid values: Standard \$1 Enterprise \$1 Web \$1 Express
+ **SubnetId**
Type: String
Description: (Optional) The subnet in which to launch the new EC2 instance. The subnet must have outbound connectivity to AWS services. If a value for SubnetId is not provided, the automation uses the default subnet.
+ **TempDbDirectorySize**
Type: String
Description: (Optional) Desired volume size (GiB) of the SQL Server TempDB directory for the new EC2 instance.
Default value: 100
## Required IAM permissions
The `AutomationAssumeRole` parameter requires the following actions to successfully use the runbook.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags",
"ec2:DescribeImages",
"ec2:DescribeInstanceStatus",
"ec2:DescribeInstances",
"ec2:RebootInstances",
"ec2:RunInstances",
"ssm:DescribeInstanceInformation",
"ssm:GetAutomationExecution",
"ssm:ListCommandInvocations",
"ssm:ListCommands",
"ssm:SendCommand",
"ssm:StartAutomationExecution"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/ROLENAME"
}
]
}
```
------
## Document Steps
To use this automation, follow the steps that apply to your instance type:
**For new EC2 instances:**
1. `aws:executeAwsApi` - Retrieve the AMI ID for SQL Server 2017 on Ubuntu 16.04.
1. `aws:runInstances` - Launch a new EC2 instance for Linux.
1. `aws:waitForAwsResourceProperty` - Wait for the newly created EC2 instance to be ready.
1. `aws:executeAwsApi` - Reboot the instance if the instance is not ready.
1. `aws:assertAwsResourceProperty` - Verify that SSM Agent is installed.
1. `aws:runCommand` - Run the SQL Server restore script in PowerShell.
**For existing EC2 instances:**
1. `aws:waitForAwsResourceProperty` - Verify that the EC2 instance is ready.
1. `aws:executeAwsApi` - Reboot the instance if the instance is not ready.
1. `aws:assertAwsResourceProperty` - Verify that SSM Agent is installed.
1. `aws:runCommand` - Run the SQL Server restore script in PowerShell.
**Outputs**
getInstance.InstanceId
restoreToNewInstance.Output
restoreToExistingInstance.Output
# `AWSSupport-ActivateWindowsWithAmazonLicense`
**Description**
The `AWSSupport-ActivateWindowsWithAmazonLicense` runbook activates an Amazon Elastic Compute Cloud (Amazon EC2) instance for Windows Server with a license provided by Amazon. The automation verifies and configures required key management service operating system settings and attempts activation. This includes operating system routes to Amazon's key management servers and key management service operating system settings. Setting the `AllowOffline` parameter to `true` allows the automation to successfully target instances that are not managed by AWS Systems Manager, but requires a stop and start of the instance.
**Note**
This runbook cannot be used on Bring Your Own License (BYOL) model Windows Server instances. For information about using your own license, see [Microsoft Licensing on AWS](https://aws.amazon.com/windows/resources/licensing/).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ActivateWindowsWithAmazonLicense)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
+ AllowOffline
Type: String
Valid values: true \$1 false
Default: false
Description: (Optional) Set it to `true` if you allow an offline Windows activation remediation in case the online troubleshooting fails, or if the provided instance is not a managed instance.
**Important**
The offline method requires that the provided EC2 instance be stopped and then started. Data stored in instance store volumes will be lost. The public IP address will change if you are not using an Elastic IP.
+ 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.
+ ForceActivation
Type: String
Valid values: true \$1 false
Default: false
Description: (Optional) Set it to `true` if you want to proceed even if Windows is already activated.
+ InstanceId
Type: String
Description: (Required) ID of your managed EC2 instance for Windows Server.
+ SubnetId
Type: String
Default: CreateNewVPC
Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the offline troubleshooting. Use `SelectedInstanceSubnet` to use the same subnet as your instance, or use `CreateNewVPC` to create a new VPC. IMPORTANT: The subnet must be in the same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
We recommend that the EC2 instance receiving the command has an IAM role with the **AmazonSSMManagedInstanceCore** Amazon managed policy attached. You must have at least **ssm:StartAutomationExecution** and **ssm:SendCommand** to run the automation and send the command to the instance, plus **ssm:GetAutomationExecution** to be able to read the automation output. For the offline remediation, see the permissions needed by `AWSSupport-StartEC2RescueWorkflow`.
**Document Steps**
1. `aws:assertAwsResourceProperty` - Check the provided instance's platform is Windows.
1. `aws:assertAwsResourceProperty` - Confirm the provided instance is a managed instance:
1. (Online activation fix) If the input instance is a managed instance, then run `aws:runCommand` to run the PowerShell script to attempt to fix Windows activation.
1. (Offline activation fix) If the input instance is not a managed instance:
1. `aws:assertAwsResourceProperty` - Verifies the `AllowOffline` flag is set to `true`. If so, the offline fix starts; otherwise the automation ends.
1. `aws:executeAutomation` - Invoke `AWSSupport-StartEC2RescueWorkflow` with the Windows activation offline fix script. The script uses either EC2Config or EC2Launch, depending on the OS version.
1. `aws:executeAwsApi` - Read the result from `AWSSupport-StartEC2RescueWorkflow`.
**Outputs**
activateWindows.Output
getActivateWindowsOfflineResult.Output
# `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2`
**Description**
The `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2` runbook analyzes connectivity from an Amazon Elastic Compute Cloud (Amazon EC2) instance or elastic network interface to an AWS service endpoint. IPv6 is not supported. The runbook uses the value that you specify for the `ServiceEndpoint` parameter to analyze connectivity to an endpoint. If an AWS PrivateLink endpoint can't be found in your VPC, the runbook uses a public IP address for the service in the current AWS Region. This automation uses Reachability Analyzer from Amazon Virtual Private Cloud. For more information, see [What is Reachability Analyzer?](https://docs.aws.amazon.com/vpc/latest/reachability/what-is-reachability-analyzer.html), in *Reachability Analyzer*.
This automation checks the following:
+ Checks whether your virtual private cloud (VPC) is configured to use the Amazon provided DNS server.
+ Checks whether an AWS PrivateLink endpoint exists in the VPC for the AWS service that you specify. If an endpoint is found, the automation verifies that the `privateDns` attribute is turned on.
+ Checks if the AWS PrivateLink endpoint is using the default endpoint policy.
**Considerations**
+ You are charged per analysis run between a source and destination. For more information, see [Amazon VPC Pricing](https://aws.amazon.com/vpc/pricing/).
+ During the automation, a network insights path and network insights analysis are created. If the automation completes successfully, the runbook deletes these resources . If the cleanup step fails, the network insights path is not deleted by the runbook and you will need to delete it manually. If you don't delete the network insights path manually, it continues to count towards the quota for your AWS account. For more information about quotas for Reachability Analyzer, see [Quotas for Reachability Analyzer](https://docs.aws.amazon.com//vpc/latest/reachability/reachability-analyzer-limits.html) in *Reachability Analyzer*.
+ Operating system-level configurations such as the use of a proxy, local DNS resolver, or hosts file can affect connectivity even if the Reachability Analyzer returns `PASS`.
+ Review the evaluation of all checks performed by the Reachability Analyzer. If any of the checks return with a status of `FAIL`, that might affect connectivity even if the overall reachability check returns a status of `PASS`.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ Source
Type: String
Description: (Required) The ID of the Amazon EC2 instance or the network interface from which you want to analyze reachability.
+ ServiceEndpoint
Type: String
Description: (Required) The hostname of the service endpoint that you want to analyze reachability to.
+ RetainVpcReachabilityAnalysis
Type: String
Default: false
Description: (Optional) Determines whether the network insight path and related analysis created are retained. By default, the resources used for analyze reachability are deleted after successful analysis. If you choose to retain the analysis, the runbook does not delete the analysis and you can visualize it in the Amazon VPC console. A console link is available in the automation output.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:CreateNetworkInsightsPath`
+ `ec2:DeleteNetworkInsightsAnalysis`
+ `ec2:DeleteNetworkInsightsPath`
+ `ec2:DescribeAvailabilityZones`
+ `ec2:DescribeCustomerGateways`
+ `ec2:DescribeDhcpOptions`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInternetGateways`
+ `ec2:DescribeManagedPrefixLists`
+ `ec2:DescribeNatGateways`
+ `ec2:DescribeNetworkAcls`
+ `ec2:DescribeNetworkInsightsAnalyses`
+ `ec2:DescribeNetworkInsightsPaths`
+ `ec2:DescribeNetworkInterfaces`
+ `ec2:DescribePrefixLists`
+ `ec2:DescribeRegions`
+ `ec2:DescribeRouteTables`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeSubnets`
+ `ec2:DescribeTransitGatewayAttachments`
+ `ec2:DescribeTransitGatewayPeeringAttachments`
+ `ec2:DescribeTransitGatewayConnects`
+ `ec2:DescribeTransitGatewayRouteTables`
+ `ec2:DescribeTransitGateways`
+ `ec2:DescribeTransitGatewayVpcAttachments`
+ `ec2:DescribeVpcAttribute`
+ `ec2:DescribeVpcEndpoints`
+ `ec2:DescribeVpcEndpointServiceConfigurations`
+ `ec2:DescribeVpcPeeringConnections`
+ `ec2:DescribeVpcs`
+ `ec2:DescribeVpnConnections`
+ `ec2:DescribeVpnGateways`
+ `ec2:GetManagedPrefixListEntries`
+ `ec2:GetTransitGatewayRouteTablePropagations`
+ `ec2:SearchTransitGatewayRoutes`
+ `ec2:StartNetworkInsightsAnalysis`
+ `elasticloadbalancing:DescribeListeners`
+ `elasticloadbalancing:DescribeLoadBalancerAttributes`
+ `elasticloadbalancing:DescribeLoadBalancers`
+ `elasticloadbalancing:DescribeRules`
+ `elasticloadbalancing:DescribeTags`
+ `elasticloadbalancing:DescribeTargetGroups`
+ `elasticloadbalancing:DescribeTargetHealth`
+ `tiros:CreateQuery`
+ `tiros:GetQueryAnswer`
+ `tiros:GetQueryExplanation`
**Document Steps**
1. `aws:executeScript`: Validates the service endpoint by attempting to resolve the hostname.
1. `aws:executeScript`: Gathers details about the VPC and subnet.
1. `aws:executeScript`: Evaluates the DNS configuration of the VPC.
1. `aws:executeScript`: Evaluates the VPC endpoint checks.
1. `aws:executeScript`: Locates an internet gateway to connect to the public service endpoint.
1. `aws:executeScript`: Determines the destination to be used for reachability analysis.
1. `aws:executeScript`: Analyzes the reachability from source to the endpoint using Reachability Analyzer and cleans up the resources if the analysis is successful.
1. `aws:executeScript`: Generates a reachability evaluation report.
1. `aws:executeScript`: Generates the output in JSON.
**Outputs**
+ `generateReport.EvalReport` - The results of the checks performed by the automation in text format.
+ `generateJsonOutput.Output` - A minimal version of the results in JSON format.
# `AWSPremiumSupport-ChangeInstanceTypeIntelToAMD`
**Description**
The`AWSPremiumSupport-ChangeInstanceTypeIntelToAMD` runbook automates migrations from Intel powered Amazon Elastic Compute Cloud (Amazon EC2) instances to the equivalent AMD powered instance types. This runbook supports general purpose (M), burstable general purpose (T), compute optimized (C), and memory optimized (R) instances built on the Nitro system. This runbook can be used on instances that aren't managed by Systems Manager.
To reduce the potential risk of data loss and downtime, the runbook checks the instance's stop behavior, whether the instance is in an Amazon EC2 Auto Scaling group, the health of the instance, and that the equivalent AMD powered instance type is available in the same Availability Zone. By default, this runbook will not change the instance type if instance store volumes are attached, or if the instance is part of an AWS CloudFormation stack. If you want to change this behavior, specify `yes` for either of the `AllowInstanceStoreInstances` and `AllowCloudFormationInstances` parameters.
**Important**
Access to `AWSPremiumSupport-*` runbooks requires a Business \$1 Support, Enterprise Support or Unified Operations Subscription. For more information, see [Compare AWS Support Plans](https://aws.amazon.com/premiumsupport/plans/).
**Considerations**
+ We recommend backing up your instance before using this runbook.
+ Changing the instance type requires the runbook to stop your instance. When an instance is stopped, any data stored in the RAM or the instance store volumes is lost, and the automatic public IPv4 address is released. For more information, see [Stop and start your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html).
+ If you don't specify a value for the `TargetInstanceType` parameter, the runbook attempts to identify the equivalent AMD instance in terms of virtual CPUs and memory within the same instance family. The runbook ends if it is not able to identify an equivalent AMD instance type.
+ By using the `DryRun` option, you can capture the equivalent AMD instance type, and validate requirements without actually changing the instance type.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSPremiumSupport-ChangeInstanceTypeIntelToAMD)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ Acknowledge
Type: String
Description: (Required) Enter `yes` to acknowledge that your target instance will be stopped if it's running.
+ InstanceId
Type: String
Description: (Required) The ID of Amazon EC2 instance whose type you want to change.
+ TargetInstanceType
Type: String
Default: automatic
Description: (Optional) The AMD instance type you want to change your instance to. The default `automatic` value uses the equivalent instance type in terms of virtual CPUs and memory. For example, an m5.large would be changed to m5a.large.
+ AllowInstanceStoreInstances
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If you specify `yes`, the runbook runs on instances that have instance store volumes attached.
+ AllowCloudFormationInstances
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If set to `yes`, the runbook runs on instances that are part of a CloudFormation stack.
+ AllowCrossGeneration
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If set to `yes`, the runbook attempts to find the newest equivalent AMD instance type within the same instance family.
+ DryRun
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If set to `yes`, the runbook returns the equivalent AMD instance type and validates migration requirements without making changes to the instance type.
+ SleepWait
Type: String
Default: PT3S
Description: (Optional) The time the runbook should wait before starting a new automation. The value you provide for this parameter must match the ISO 8601 standard. For more information about creating ISO 8601 strings, see [Formatting date and time strings for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-datetime-strings.html#systems-manager-datetime-strings-format).
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:DescribeAutomationExecutions`
+ `ssm:GetAutomationExecution`
+ `ssm:StartAutomationExecution`
+ `ec2:GetInstanceTypesFromInstanceRequirements`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DescribeInstanceTypeOfferings`
+ `ec2:DescribeInstanceTypes`
+ `ec2:DescribeTags`
+ `ec2:ModifyInstanceAttribute`
+ `ec2:StartInstances`
+ `ec2:StopInstances`
**Document Steps**
1. `aws:assertAwsResourceProperty`: Confirms the status of the target Amazon EC2 instance is `running`, `pending`, `stopped`, or `stopping`. Otherwise, the automation ends.
1. `aws:executeAwsApi`: Gathers properties from the target Amazon EC2 instance.
1. `aws:branch`: Branches the automation based on the state of the Amazon EC2 instance.
1. If `stopped` or `stopping`, the automation runs `aws:waitForAwsResourceProperty` until the Amazon EC2 instance is fully stopped.
1. If `running` or `pending`, the automation runs `aws:waitForAwsResourceProperty` until the Amazon EC2 instance passes status checks.
1. `aws:assertAwsResourceProperty`: Confirms the Amazon EC2 instance is not part of an Auto Scaling group by checking if the `aws:autoscaling:groupName` tag is applied.
1. `aws:executeAwsApi`: Gathers the current instance type properties to find the equivalent AMD instance type.
1. `aws:assertAwsResourceProperty`: Confirms a AWS Marketplace product code is not associated with the Amazon EC2 instance. Some products are not available on all instance types.
1. `aws:branch`: Branches the automation depending on whether you want the automation to check if the Amazon EC2 instance is part of a CloudFormation stack
1. If the `aws:cloudformation:stack-name` tag is applied to the instance, the automation runs `aws:assertAwsResourceProperty` to confirm the instance is not part of a CloudFormation stack.
1. `aws:branch`: Branches the automation based on whether the instance root volume type is Amazon Elastic Block Store (Amazon EBS).
1. `aws:assertAwsResourceProperty`: Confirms the instance shutdown behavior is `stop` and not `terminate`.
1. `aws:executeScript`: Confirms there is only one automation of this runbook targeting the current instance. If another automation is already in progress targeting the same instance, it returns an error and ends.
1. `aws:executeAwsApi`: Returns a list of the AMD instance types with same amount of memory and vCPUs.
1. `aws:executeScript`: Checks if the current instance type is supported and returns its equivalent AMD instance type. If there is no equivalent, the automation ends.
1. `aws:executeScript`: Confirms the AMD instance type is available in the same Availability Zone, and verifies the provided IAM permissions.
1. `aws:branch`: Branches the automation based on whether the `DryRun` parameter value is `yes`.
1. `aws:branch`: Checks if the original and the target instance type are the same. If they're the same, the automation ends.
1. `aws:executeAwsApi`: Gets the current instance state.
1. `aws:changeInstanceState`: Stops the Amazon EC2 instance.
1. `aws:changeInstanceState`: Forces the instance to stop if it's stuck in stopping state.
1. `aws:executeAwsApi`: Changes the instance type to the target AMD instance type.
1. `aws:sleep`: Waits 3 seconds after changing the instance type for eventual consistency.
1. `aws:branch`: Branches the automation based on the previous instance state. If it was `running`, the instance is started.
1. `aws:changeInstanceState`: Starts the Amazon EC2 instance if it was running before changing the instance type.
1. `aws:waitForAwsResourceProperty`: Waits for the Amazon EC2 instance to pass status checks. If the instance doesn't pass status checks, the instance is changed back to its original instance type.
1. `aws:changeInstanceState`: Stops the Amazon EC2 instance before changing it to its original instance type.
1. `aws:changeInstanceState`: Forces the Amazon EC2 instance to stop before changing it to its original instance type in case it gets stuck in a stopping state.
1. `aws:executeAwsApi`: Changes Amazon EC2 instance to its original type.
1. `aws:sleep`: Waits 3 seconds after changing instance type for eventual consistency.
1. `aws:changeInstanceState`: Starts the Amazon EC2 instance if it was running before changing the instance type.
1. `aws:waitForAwsResourceProperty`: Waits for the Amazon EC2 instance to pass status checks.
1. `aws:sleep`: Waits before ending the runbook.
# `AWSSupport-CheckXenToNitroMigrationRequirements`
**Description**
The `AWSSupport-CheckXenToNitroMigrationRequirements` runbook verifies that an Amazon Elastic Compute Cloud (Amazon EC2) instance meets the prerequistes to successfully change the instance type from a Xen type instance to Nitro-based instance type. This automation checks the following:
+ The root device is an Amazon Elastic Block Store (Amazon EBS) volume.
+ The `enaSupport` attribute is enabled.
+ The ENA module is installed on the instance.
+ The NVMe module is installed on the instance. If yes, the module is installed and a script verifies that the module is loaded in the `initramfs` image.
+ Analyzes `/etc/fstab` and looks for block devices being mounted using device names.
+ Determines whether the operating system (OS) uses predictable network interface names by default.
This runbook supports the following operating systems:
+ Red Hat Enterprise Linux
+ CentOS
+ Amazon Linux 2
+ Amazon Linux
+ Debian Server
+ Ubuntu Server
+ SUSE Linux Enterprise Server 15 SP2
+ SUSE Linux Enterprise Server 12 SP5
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-CheckXenToNitroMigrationRequirements)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
+ InstanceId
Type: String
Default: false
Description: (Required) The ID of the Amazon EC2 instance which you want to check prerequisites for before migrating to a Nitro-based instance type.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:DescribeAutomationExecutions`
+ `ssm:DescribeAutomationStepExecutions`
+ `ssm:DescribeAutomationStepExecutions`
+ `ssm:DescribeInstanceInformation`
+ `ssm:DescribeInstanceProperties`
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:GetDocument`
+ `ssm:ListCommands`
+ `ssm:ListCommandInvocations`
+ `ssm:ListDocuments`
+ `ssm:StartAutomationExecution`
+ `ssm:SendCommand`
+ `iam:ListRoles`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstancesTypes`
**Document Steps**
+ `aws:executeAwsApi` - Gathers details about the instance.
+ `aws:executeAwsApi` - Gathers information about the hypervisor for the instance.
+ `aws:branch` - Branches based on whether the target instance is already running a Nitro-based instance type.
+ `aws:branch` - Checks whether the instance's OS is supported by Nitro-based instances.
+ `aws:assertAwsResourceProperty` - Verifies the instance you specified is managed by Systems Manager, and that the status is `Online`.
+ `aws:branch` - Branches based on whether the root device of the instance is an Amazon EBS volume.
+ `aws:branch` - Branches based on whether the ENA attribute is enabled for the instance.
+ `aws:runCommand` - Checks for ENA drivers on the instance.
+ `aws:runCommand` - Checks for NVMe drivers on the instance.
+ `aws:runCommand` - Checks the `fstab` file for unrecognized formats.
+ `aws:runCommand` - Checks for predictable interface name configuration on the instance.
+ `aws:executeScript` - Generates output based on previous steps.
**Outputs**
finalOutput.output - The results of the checks performed by the automation.
# `AWSSupport-CloneXenEC2InstanceAndMigrateToNitro`
**Description**
The **AWSSupport-CloneXenEC2InstanceAndMigrateToNitro**runbook clones, prepares and migrates the cloned Amazon Elastic Compute Cloud (Amazon EC2) Linux instance, currently running on Amazon EC2 Xen platform, to run on [Amazon EC2 Nitro platform](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances). This automation is divided into three different branches:
+ **Preliminary Checks**: Evaluates all prerequisites to proceed with the migration including checking if the target Amazon EC2 instance is already running on Nitro platform, determining lifecycle status, validating operating system, and verifying Systems Manager connectivity.
+ **Test**: Creates a test AMI from the target Amazon EC2 instance and launches a test Amazon EC2 instance to validate the migration process before proceeding.
+ **CloneAndMigrate**: Creates a clone of the target Amazon EC2 instance, installs necessary drivers, configures the system for Nitro platform, and changes the instance type to the desired Nitro type.
**Important**
Before providing approval to stop the target Amazon EC2 instance, ensure that all applications running on the instance are gracefully closed. If the Amazon EC2 instance does not have an Elastic IP address associated, the automatic public IPv4 address will change once the instance is stopped and started.
**Important**
**Disclaimer**: Executing this runbook may incur extra charges to your account for the Amazon EC2 instance, Amazon EBS Volumes & AMIs. Please refer to the [Amazon EC2 Pricing](https://aws.amazon.com/ec2/pricing/) & [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/) for more details.
**Important**
**Prerequisites**
The target Amazon EC2 instance requires outbound access to the repositories to install drivers and dependencies such as `kernel-devel`, `gcc`, `patch`, `rpm-build`, `wget`, `dracut`, `make`, `linux-headers`, and `unzip` using package manager if needed.
**Supported Operating Systems**
+ Red Hat Enterprise Linux (RHEL) 8 and 9
+ Amazon Linux 2 and AL2023
+ Ubuntu Server 18.04 LTS, 20.04 and 22.04
+ Debian 11 and 12 (AWS partition only)
+ SUSE12SP5 and SUSE15SP(5,6)
**How does it work?**
The runbook performs the following high-level steps:
+ Validates prerequisites and checks if the instance is suitable for migration.
+ Creates and tests an AMI to ensure the migration will be successful.
+ Enables Enhanced networking (ENA) attribute and installs the latest ENA drivers.
+ Verifies and configures NVMe module in initramfs.
+ Analyzes and modifies /etc/fstab to replace device names with UUIDs.
+ Disables predictable interface naming and removes persistent network rules.
+ Changes the cloned instance type to the desired Nitro type.
+ Creates a final AMI that can be used as a Golden Image for launching Nitro instances.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-CloneXenEC2InstanceAndMigrateToNitro)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `autoscaling:DescribeAutoScalingInstances`
+ `ec2:CreateImage`
+ `ec2:CreateTags`
+ `ec2:DescribeImages`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DescribeInstanceTypeOfferings`
+ `ec2:DescribeInstanceTypes`
+ `ec2:DeregisterImage`
+ `ec2:ModifyInstanceAttribute`
+ `ec2:RunInstances`
+ `ec2:StartInstances`
+ `ec2:StopInstances`
+ `ec2:TerminateInstances`
+ `iam:PassRole`
+ `sns:Publish`
+ `ssm:DescribeAutomationExecutions`
+ `ssm:DescribeInstanceInformation`
+ `ssm:SendCommand`
Example IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingInstances",
"ec2:CreateImage",
"ec2:CreateTags",
"ec2:DescribeImages",
:ec2:DescribeInstanceAttribute:,
"ec2:DescribeInstances",
"ec2:DescribeInstanceStatus",
"ec2:DescribeInstanceTypes",
"ec2:DeregisterImage",
"ec2:ModifyInstanceAttribute",
"ec2:RunInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:TerminateInstances",
"iam:PassRole",
"ssm:DescribeAutomationExecutions",
"ssm:DescribeInstanceInformation",
"ssm:SendCommand"
],
"Resource": "*"
}
]
}
```
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-CloneXenEC2InstanceAndMigrateToNitro/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-CloneXenEC2InstanceAndMigrateToNitro/description) in Systems Manager under Documents.
1. Select **`Execute automation`**.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
+ Description: (Optional) The 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.
+ Type: `AWS::IAM::Role::Arn`
+ **TargetInstanceId (Required):**
+ Description: (Required) Instance ID of the target Amazon EC2 instance you want to migrate to Nitro platform.
+ Type: `AWS::EC2::Instance::Id`
+ **NitroInstanceType (Optional):**
+ Description: (Optional) Enter the destination Nitro instance type. Only Nitro M5, M6, C5, C6, R5, R6 and T3 instances are supported (e.g. t3.small). Default: m5.xlarge.
+ Type: `String`
+ Allowed Pattern: `^(m5a?z?d?n?|c5a?d?n?|r5a?d?n?b?|(c|m|r)6(a|i)?d?)\\.(2|4|8|12|16|24|32)?xlarge$|^t3a?\\.((x|2x)?large|nano|micro|small|medium)$`
+ Default: `m5.xlarge`
+ **SNSTopicArn (Required):**
+ Description: (Required) Provide the ARN of the Amazon SNS Topic for approval notification. This Amazon SNS topic is used to send approval notifications during the automation execution.
+ Type: `String`
+ Allowed Pattern: `^arn:(aws|aws-cn|aws-us-gov|aws-iso(-[a-z])?):sns:(us(-gov|-isob?)?|ap|ca|af|me|cn|eu|sa)-(central|(north|south)?(east|west)?)-\\d:\\d{12}:[a-zA-Z0-9_.-]{1,256}$`
+ **ApproverIAM (Required):**
+ Description: (Required) Provide a list of AWS authenticated principals who are able to either approve or reject the action. The maximum number of approvers is 10.
+ Type: `StringList`
+ Allowed Pattern: `^[a-zA-Z0-9_+=,.@\\-\/]{1,128}$|^arn:(aws|aws-cn|aws-us-gov|aws-iso(-[a-z])?):(sts|iam)::[0-9]{12}:[a-zA-Z0-9_+=,.@\\-\/]{1,256}$`
+ **MinimumRequiredApprovals (Optional):**
+ Description: (Optional) The minimum number of approvals required to resume the automation. Default: 1.
+ Type: Integer
+ Default: 1
+ **DeleteResourcesOnFailure (Optional):**
+ Description: (Optional) Whether to terminate the cloned Amazon EC2 instance and AMI if the automation fails.
+ Type: `Boolean`
+ Allowed Values: `[true, false]`
+ Default: `true`
+ **Acknowledgement (Required):**
+ Description: (Required) Please read the complete details of the actions performed by this automation runbook and write 'Yes, I understand and acknowledge' if you acknowledge the steps.
+ Type: `String`
+ Allowed Pattern: `^Yes, I understand and acknowledge$`
+ **AllowInstanceStoreInstances (Optional):**
+ Description: (Optional) If you specify `yes`, the runbook runs on instances that have instance store volumes attached. **Warning:** data in the instance store volumes is lost when the instance is stopped. This parameter helps avoid accidental data loss.
+ Type: `Boolean`
+ Allowed Values: `[yes, no]`
+ Default: `no`
1. Select **Execute**.
1. The automation initiates.
1. The document performs the following steps:
+ **`checkConcurrency`**:
Ensures there is only one execution of this runbook targeting the current Amazon EC2 instance.
+ **`getTargetInstanceProperties`**:
Fetches the details of the target Amazon EC2 instance.
+ **`checkIfNitroInstanceTypeIsSupportedInAZ`**:
Determines if the target Nitro instance type is supported in the same Availability Zone as the target Amazon EC2 instance.
+ **`createTestImage`**:
Creates a test AMI from the provided instance.
+ **`launchTestInstanceInSameSubnet`**:
Launches a test Amazon EC2 instance from the test AMI using the same configuration as target Amazon EC2 instance.
+ **`approvalToStopTargetInstance`**:
Waits for designated principals approval to stop the target instance.
+ **`createBackupImage`**:
Creates an AMI from the provided instance for backup.
+ **`launchInstanceInSameSubnet`**:
Launches a new Amazon EC2 instance from the backup AMI using the same configuration as source Amazon EC2 instance.
+ **`checkAndInstallENADrivers`**:
Determines the availability of Enhanced Networking Adapter (ENA) drivers on the Amazon EC2 instance and installs, if missing.
+ **`checkAndAddNVMEDrivers`**:
Determines the availability of NVMe drivers on the cloned Amazon EC2 instance and installs, if missing.
+ **`checkAndModifyFSTABEntries`**:
Determines if the device name are used in `/etc/fstab` and replaces them with their UUIDs, if found.
+ **`setNitroInstanceTypeForClonedInstance`**:
Sets the provided target Amazon EC2 instance type for the cloned Amazon EC2 instance.
+ **`approvalForCreatingImageAfterDriversInstallation`**:
Waits for user approval if the cloned Amazon EC2 instance successfully boots on Nitro platform.
+ **`createImageAfterDriversInstallation`**:
Creates an Image from the new Amazon EC2 instance only if the new Amazon EC2 instance successfully boots on Nitro Platform.
1. After completed, review the **Outputs** section for the detailed results of the execution.
**References**
AWS Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-CloneXenEC2InstanceAndMigrateToNitro/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSSupport-CollectSAPHANALogs`
**Description**
The `AWSSupport-CollectSAPHANALogs` runbook collects system logs from SAP HANA on an Amazon Elastic Compute Cloud (Amazon EC2) instance that is part of an SAP on AWS deployment. The Amazon EC2 instance must be managed by AWS Systems Manager (Systems Manager). The runbook checks for required packages and installs them if missing, runs the appropriate log collection tool for the detected operating system, and optionally uploads the collected logs to an Amazon Simple Storage Service (Amazon S3) bucket.
**Important**
This runbook requires at least 200 MB of available disk space on the `/var/log` partition. Running this runbook may install additional packages on the target Amazon EC2 instance. You must acknowledge this by setting the `Acknowledgement` parameter to `Yes`. Storing logs in Amazon S3 incurs standard Amazon S3 storage and request charges.
**Supported operating systems**
+ Red Hat Enterprise Linux 8.4 and later
+ SUSE Linux Enterprise Server 12 SP5
+ SUSE Linux Enterprise Server 15 SP3 and later
**Packages installed if missing**
SUSE Linux Enterprise Server:
+ `supportutils`
+ `yast2-support`
+ `supportutils-plugin-suse-public-cloud`
+ `supportutils-plugin-ha-sap`
+ `crmsh`
+ `unzip`
+ `curl`
+ `aws-cli` (optional, installed if `InstallAWSCLI` is set to `Yes`)
Red Hat Enterprise Linux:
+ `sos`
+ `crm_report`
+ `unzip`
+ `curl`
+ `aws-cli` (optional, installed if `InstallAWSCLI` is set to `Yes`)
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-CollectSAPHANALogs)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
+ InstanceID
Type: AWS::EC2::Instance::Id
Description: (Required) The ID of the Amazon EC2 instance running the SAP workload from which logs should be collected.
+ Acknowledgement
Type: String
Valid values: Yes
Description: (Required) I acknowledge that this runbook may install additional packages in the target Amazon EC2 instance for log collection.
+ S3LogDestination
Type: AWS::S3::Bucket::Name
Description: (Optional) The name of the Amazon S3 bucket to which logs are uploaded. The bucket must not be public and must belong to the same AWS account. If not provided, logs are stored in instance local storage.
+ S3Prefix
Type: String
Default: AWSSupport-CollectSAPHANALogs
Allowed pattern: `^$|^[a-zA-Z0-9][-./a-zA-Z0-9]{0,255}$`
Description: (Optional) The Amazon S3 bucket prefix where logs are stored. If not provided, defaults to `AWSSupport-CollectSAPHANALogs`.
+ InstallAWSCLI
Type: String
Valid values: Yes \$1 No
Default: No
Description: (Optional) Whether to install the AWS CLI on the instance. If `Yes`, the runbook installs the AWS CLI if not already present.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:DescribeInstanceInformation`
+ `ssm:SendCommand`
+ `ssm:GetCommandInvocation`
+ `s3:GetBucketPublicAccessBlock`
+ `s3:GetBucketAcl`
+ `s3:GetBucketLocation`
+ `s3:GetBucketOwnershipControls`
+ `s3:GetEncryptionConfiguration`
+ `s3:PutObject`
**Document Steps**
1. `AssertInstanceIsSSMManaged` - Verifies that the target Amazon EC2 instance is managed by Systems Manager and has a `PingStatus` of `Online`. The runbook cancels if the instance is not managed.
1. `GetInstanceInformation` - Retrieves information about the specified Amazon EC2 instance, including the platform name, which is used to determine the appropriate log collection method.
1. `CollectLogs` - Runs a shell script on the instance to collect logs. For SUSE Linux Enterprise Server instances, the script uses `supportconfig`. For Red Hat Enterprise Linux instances, it uses `sos report`. For HA clusters, the script also collects additional HA logs from the last 7 days using the `crm report` command. Required packages are installed if missing.
1. `BranchOnS3BucketProvided` - Branches the execution based on whether an Amazon S3 bucket was provided in `S3LogDestination`. If no bucket was provided, the runbook skips to `GenerateReport`. Otherwise, it proceeds to `CheckS3BucketPublicStatus`.
1. `CheckS3BucketPublicStatus` - Checks if the Amazon S3 bucket specified in `S3LogDestination` is configured with server-side encryption (SSE), and if it allows anonymous or public read or write access permissions. Also verifies that the actual bucket owner is the same as the expected bucket owner. If this step fails, the runbook continues to `GenerateReport` without uploading.
1. `UploadLogsToS3` - Uploads the collected logs to the specified Amazon S3 bucket. If `InstallAWSCLI` is set to `Yes` and the AWS CLI is not installed, the script installs AWS CLI before uploading.
1. `GenerateReport` - Generates a report of the log collection process. If an Amazon S3 bucket was provided, it includes the Amazon S3 bucket name and prefix where logs were uploaded. If not, it indicates that logs were stored locally on the instance. It also reports why any previous steps failed.
**Outputs**
`GenerateReport.Summary` - A summary of the log collection result.
`GenerateReport.LogLocation` - The location where logs were stored, either a local path on the instance or an Amazon S3 URI.
`GenerateReport.Status` - The overall status of the log collection execution.
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-CollectSAPHANALogs/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-CollectSAPHANALogs/description) in Systems Manager under Documents.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
The ARN of the IAM role that allows Systems Manager Automation to perform actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user who starts this runbook.
+ **InstanceID (Required):**
The ID of the Amazon EC2 instance running the SAP workload.
+ **Acknowledgement (Required):**
Enter `Yes` to acknowledge that the runbook may install additional packages on the target Amazon EC2 instance.
+ **S3LogDestination (Optional):**
The name of the Amazon S3 bucket to upload logs to. If not provided, logs are stored locally on the instance.
+ **S3Prefix (Optional):**
The Amazon S3 bucket prefix for stored logs. Defaults to `AWSSupport-CollectSAPHANALogs`.
+ **InstallAWSCLI (Optional):**
Select `Yes` to automatically install the AWS CLI if it is not present on the instance. Defaults to `No`.
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **`AssertInstanceIsSSMManaged`**
Verifies that the target Amazon EC2 instance is managed by Systems Manager and has a `PingStatus` of `Online`.
+ **`GetInstanceInformation`**
Retrieves information about the specified Amazon EC2 instance, including the platform name.
+ **`CollectLogs`**
Runs a shell script to collect logs using `supportconfig` for SLES or `sos report` for RHEL. For HA clusters, also collects HA logs from the last 7 days using `crm report`.
+ **`BranchOnS3BucketProvided`**
Skips to `GenerateReport` if no Amazon S3 bucket was provided, otherwise proceeds to `CheckS3BucketPublicStatus`.
+ **`CheckS3BucketPublicStatus`**
Verifies the Amazon S3 bucket has SSE enabled, does not allow public access, and is owned by the same AWS account.
+ **`UploadLogsToS3`**
Uploads the collected logs to the specified Amazon S3 bucket. Installs the AWS CLI if `InstallAWSCLI` is `Yes` and it is not already present.
+ **`GenerateReport`**
Generates a summary of the log collection result, including the log location and any step failures.
1. After completion, review the Outputs section for the detailed results of the execution.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-CollectSAPHANALogs/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows landing page](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSSupport-ConfigureEC2Metadata`
**Description**
This runbook helps you configure instance metadata service (IMDS) options for Amazon Elastic Compute Cloud (Amazon EC2) instances. Using this runbook, you can configure the following:
+ Enforce the use of IMDSv2 for instance metadata.
+ Configure the `HttpPutResponseHopLimit` value.
+ Allow or deny instance metadata access.
For more information about instance metadata, see [Configuring the Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) in the *Amazon EC2 User Guide*.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ConfigureEC2Metadata)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ EnforceIMDSv2
Type: String
Valid values: required \$1 optional
Default: optional
Description: (Optional) Enforce IMDSv2. If you choose `required`, the Amazon EC2 instance will only use IMDSv2. If you choose `optional`, you can choose between IMDSv1 and IMDSv2 for metadata access.
**Important**
If you enforce IMDSv2, applications that use IMDSv1 might not function correctly. Before enforcing IMDSv2, make sure your applications that use IMDS are upgraded to a version that support IMDSv2. For information about Instance Metadata Service Version 2 (IMDSv2), see [Configuring the Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) in the *Amazon EC2 User Guide*.
+ HttpPutResponseHopLimit
Type: Integer
Valid values: 0-64
Default: 0
Description: (Optional) The desired HTTP PUT response hop limit value (1-64) for instance metadata requests. This value controls the number of hops that the PUT response can traverse. To prevent the response from traveling outside of the instance, specify `1` for the parameter value.
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instance whose metadata settings you want to configure.
+ MetadataAccess
Type: String
Valid values: enabled \$1 disabled
Default: enabled
Description: (Optional) Allow or deny instance metadata access in the Amazon EC2 instance. If you specify `disabled`, all other parameters will be ignored and the metadata access will be denied for the instance.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeInstances`
+ `ec2:ModifyInstanceMetadataOptions`
+ `ssm:GetAutomationExecution`
+ `ssm:StartAutomationExecution`
**Document Steps**
1. branchOnMetadataAccess - Branches automation based on the value of `MetadataAccess` parameter.
1. disableMetadataAccess - Calls the ModifyInstanceMetadataOptions API action to disable metadata endpoint access.
1. branchOnHttpPutResponseHopLimit - Branches automation based on the value of `HttpPutResponseHopLimit` parameter.
1. maintainHopLimitAndConfigureImdsVersion - If `HttpPutResponseHopLimit` is 0, maintains current hop limit and changes other metadata options.
1. waitBeforeAssertingIMDSv2State - Waits 30 seconds before asserting IMDSv2 status.
1. setHopLimitAndConfigureImdsVersion - If `HttpPutResponseHopLimit` is greater than 0, configures the metadata options using the given input parameters.
1. waitBeforeAssertingHopLimit - Waits 30 seconds before asserting metadata options.
1. assertHopLimit - Asserts the `HttpPutResponseHopLimit` property is set to the value you specified.
1. branchVerificationOnIMDSv2Option - Branches verification based on the value of `EnforceIMDSv2` parameter.
1. assertIMDSv2IsOptional - Asserts `HttpTokens` value set to `optional`.
1. assertIMDSv2IsEnforced - Asserts `HttpTokens` value set to `required`.
1. waitBeforeAssertingMetadataState - Waits 30 seconds before asserting the metadata state is disabled.
1. assertMetadataIsDisabled - Asserts metadata is `disabled`.
1. describeMetadataOptions - Gets the metadata options after the changes you've specified have been applied.
**Outputs**
describeMetadataOptions.State
describeMetadataOptions.MetadataAccess
describeMetadataOptions.IMDSv2
describeMetadataOptions.HttpPutResponseHopLimit
# `AWSSupport-ContainEC2Instance`
**Description**
The `AWSSupport-ContainEC2Instance` runbook provides an automated solution for the procedure outlined in the article [How do I isolate the Amazon EC2 Instance when faced with a potentially compromised or suspicious?](https://repost.aws/articles/ARwkDzoO-8RN-SDQnA1aX-XA) The automation branches depending on the values you specify.
**How does it work?**
This Automation runbook `AWSSupport-ContainEC2Instance` performs network containment of an Amazon EC2 Instance through a series of coordinated steps. When executed in `Contain` mode, it first validates the input parameters and checks if the instance is not terminated. It then backs up the current security group configuration to an Amazon S3 bucket for later restoration. The runbook creates two security groups: a temporary "all access" security group and a final "containment" security group. It gradually transitions the instance's network interfaces from their original security groups to the all-access security group, and finally to the containment security group. If specified, it creates both unencrypted and encrypted AMI backups of the instance. For instances in an Auto Scaling group, it handles the necessary Auto Scaling group modifications and brings the instance to standby state. When executed in `Release` mode, it restores the instance to its original network configuration using the backed-up settings from Amazon S3. The runbook supports a `DryRun` parameter to preview actions without making actual changes, and includes comprehensive error handling and reporting mechanisms throughout the containment and release workflows.
**Important**
This runbook performs various operations that require elevated privileges, such as modifying security groups, creating AMIs, and interacting with Auto Scaling groups. These actions could potentially lead to privilege escalation or impact other workloads in your account. You should review the permissions granted to the role specified by the `AutomationAssumeRole` parameter and ensure they are appropriate for the intended use case. You can refer to the following AWS documentation for more information on IAM permissions: [https://docs.aws.amazon.com//IAM/latest/UserGuide/access_controlling.html](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_controlling.html) [https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup-iam.html](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup-iam.html).
This runbook performs mutative actions that could potentially cause unavailability or disruption to your workloads. Specifically, it modifies the security groups associated with the target Amazon EC2 Instance, which could impact network connectivity. Additionally, if the instance is part of an Auto Scaling group, the runbook may modify the group's configuration, potentially affecting its scaling behavior.
During the containment process, this runbook creates additional resources, such as security groups and AMIs. While these resources are tagged for identification, you should be aware of their creation and ensure proper cleanup or management after the containment process is complete.
If the `Action` parameter is set to `Release`, this runbook attempts to restore the Amazon EC2 Instance's configuration to its original state. However, there is a risk that the restoration process may fail, leaving the instance in an inconsistent state. The runbook provides instructions for manual restoration in case of such failures, but you should be prepared to handle potential issues during the restoration process.
It is recommended to review the runbook thoroughly, understand its potential impacts, and test it in a non-production environment before executing it in your production environment.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ContainEC2Instance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
/
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ autoscaling:CreateOrUpdateTags
+ autoscaling:DeleteTags
+ autoscaling:DescribeAutoScalingGroups
+ autoscaling:DescribeAutoScalingInstances
+ autoscaling:DescribeTags
+ autoscaling:EnterStandby
+ autoscaling:ExitStandby
+ autoscaling:UpdateAutoScalingGroup
+ ec2:AuthorizeSecurityGroupEgress
+ ec2:AuthorizeSecurityGroupIngress
+ ec2:CopyImage
+ ec2:CreateImage
+ ec2:CreateSecurityGroup
+ ec2:CreateSnapshot
+ ec2:CreateTags
+ ec2:DeleteSecurityGroup
+ ec2:DeleteTags
+ ec2:DescribeImages
+ ec2:DescribeInstances
+ ec2:DescribeSecurityGroups
+ ec2:DescribeSnapshots
+ ec2:DescribeTags
+ ec2:ModifyNetworkInterfaceAttribute
+ ec2:RevokeSecurityGroupEgress
+ kms:CreateGrant
+ kms:DescribeKey
+ kms:GenerateDataKeyWithoutPlaintext
+ kms:ReEncryptFrom
+ kms:ReEncryptTo
+ s3:CreateBucket
+ s3:DeleteObjectTagging
+ s3:GetAccountPublicAccessBlock
+ s3:GetBucketAcl
+ s3:GetBucketLocation
+ s3:GetBucketOwnershipControls
+ s3:GetBucketPolicy
+ s3:GetBucketPolicyStatus
+ s3:GetBucketPublicAccessBlock
+ s3:GetObject
+ s3:ListBucket
+ s3:PutAccountPublicAccessBlock
+ s3:PutBucketPolicy
+ s3:PutBucketVersioning
+ s3:PutObject
+ s3:PutObjectTagging
Example Policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ReadOperations",
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:DescribeTags",
"ec2:DescribeImages",
"ec2:DescribeInstances",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSnapshots",
"ec2:DescribeTags",
"kms:DescribeKey",
"s3:GetAccountPublicAccessBlock",
"s3:GetBucketAcl",
"s3:GetBucketLocation",
"s3:GetBucketOwnershipControls",
"s3:GetBucketPolicy",
"s3:GetBucketPolicyStatus",
"s3:GetBucketPublicAccessBlock",
"s3:GetObject",
"s3:ListBucket"
],
"Resource": "*"
},
{
"Sid": "WriteOperations",
"Effect": "Allow",
"Action": [
"autoscaling:CreateOrUpdateTags",
"autoscaling:DeleteTags",
"autoscaling:EnterStandby",
"autoscaling:ExitStandby",
"autoscaling:UpdateAutoScalingGroup",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CopyImage",
"ec2:CreateImage",
"ec2:CreateSecurityGroup",
"ec2:CreateSnapshot",
"ec2:CreateTags",
"ec2:DeleteSecurityGroup",
"ec2:DeleteTags",
"ec2:ModifyNetworkInterfaceAttribute",
"ec2:RevokeSecurityGroupEgress",
"kms:CreateGrant",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:ReEncryptFrom",
"kms:ReEncryptTo",
"s3:CreateBucket",
"s3:DeleteObjectTagging",
"s3:PutAccountPublicAccessBlock",
"s3:PutBucketPolicy",
"s3:PutBucketVersioning",
"s3:PutObject",
"s3:PutObjectTagging"
],
"Resource": "*"
}
]
}
```
------
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-ContainEC2Instance/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-ContainEC2Instance/description) in Systems Manager under Documents.
1. Select **Execute automation.**
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
+ Description: (Optional) The Amazon Resource Name (ARN) of the AWS 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 who starts this runbook.
+ Type: `AWS::IAM::Role::Arn`
+ **Action (Required):**
+ Description: (Required) Select `Contain` to isolate the Amazon EC2 instance or `Restore` to try to restore the Amazon EC2 instance configuration original configuration from a previous backup.
+ Type: String
+ Allowed Pattern: `Contain|Restore`
+ **DryRun (Optional):**
+ Description: (Optional) When set to `true`, the automation will not execute any of the commands, instead it will report on what it would have attempted to do, detailing out each step. Default value: `true`.
+ Type: Boolean
+ Allowed Values: `true|false`
+ **CreateAMIBackup (Optional):**
+ Description: (Optional) When set to `true`, an AMI of the Amazon EC2 Instance will be created before performing the containment actions.
+ Type: Boolean
+ Allowed Values: `true|false`
+ **KmsKey (Optional):**
+ Description: (Optional) The ID of the AWS KMS key that will be used to create an encrypted AMI of target Amazon EC2 instance. Default is set to `alias/aws/ebs`.
+ Type: String
+ Allowed Pattern: `^(((arn:(aws|aws-cn|aws-us-gov):kms:([a-z]{2}|[a-z]{2}-gov)-[a-z]+-[0-9]{1}:[0-9]{12}:key/)?([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|mrk-[a-f0-9]{32}))|(arn:(aws|aws-cn|aws-us-gov):kms:([a-z]{2}|[a-z]{2}-gov)-[a-z]+-[0-9]{1}:[0-9]{12}:)?alias/.{1,})$`
+ **BackupS3BucketName (Conditional):**
+ Description: (Conditional) Amazon Amazon S3 bucket to upload the configuration when `Action` is `Contain` or to restore the configuration when `Action` is `Release`. **Note: ** If the provided bucket doesn't exist in the account, the automation will create a Amazon S3 bucket on your behalf.
+ Type: `AWS::S3::Bucket::Name`
+ **TagIdentifier (Optional):**
+ Description: (Optional) A tag in the format `Key=BatchId,Value=78925` that will be added to the AWS resources created or modified by this runbook during the containment workflow. This tag can be used to identify and manage resources associated during containment process. During the restore workflow, the tag specified by this parameter will be removed from the resources. **Note:** Tag keys and values are case-sensitive.
+ Type: String
+ Allowed Pattern: `^$|^[Kk][Ee][Yy]=[\\+\\-\\=\\.\\_\\:\\/@a-zA-Z0-9]{1,128},[Vv][Aa][Ll][Uu][Ee]=[\\+\\-\\=\\.\\_\\:\\/@a-zA-Z0-9]{0,128}$`
+ **BackupS3BucketAccess (Conditional):**
+ Description: (Conditional) The ARN of the IAM users or roles that will be allowed access to the backup Amazon S3 bucket after running the containment actions. This parameter is required when `Action` is `Contain`. The `AutomationAssumeRole`, or in its absence the user under whose context the automation is running is automatically added to the list.
+ Type: String
+ Allowed Pattern: `^$|^arn:(aws|aws-cn|aws-us-gov|aws-iso(-[a-z])?):iam::[0-9]{12}:(role|user)\\/[\\w+\\/=,.@-]+$`
+ **IngressTrafficRules (Optional):**
+ Description: (Optional) A comma separated map of security group ingress rules with Cidr, IpProtocol, FromPort and ToPort in the format `[{"Cidr": "1.2.3.4/32", "IpProtocol": "tcp", "FromPort":"22", "ToPort":"22"}]` to be applied to the Amazon EC2 instance. If no rules are provided, a security group without any ingress rules will be attached to the Amazon EC2 instance, effectively isolating it from any incoming traffic.
+ Type: MapList
+ Allowed Pattern: `^\\{\\}$|^\\{\"Cidr\":\"[\\x00-\\x7F+]{1,128}\",\"IpProtocol\":\"[\\x00-\\x7F+]{1,128}\",\"FromPort\":\"[\\x00-\\x7F+]{1,128}\",\"ToPort\":\"[\\x00-\\x7F+]{0,255}\"\\}`
+ **EgressTrafficRules (Optional):**
+ Description: (Optional) A comma separated map of security group egress rules with Cidr, IpProtocol, FromPort and ToPort in the format `[{"Cidr": "1.2.3.4/32", "IpProtocol": "tcp", "FromPort":"22", "ToPort":"22"}]` to be applied to the Amazon Amazon EC2 instance. If no rules are provided, a security group without any egress rules will be attached to the Amazon EC2 instance, effectively preventing all outgoing traffic.
+ Type: MapList
+ Allowed Pattern: `^\\{\\}$|^\\{\"Cidr\":\"[\\x00-\\x7F+]{1,128}\",\"IpProtocol\":\"[\\x00-\\x7F+]{1,128}\",\"FromPort\":\"[\\x00-\\x7F+]{1,128}\",\"ToPort\":\"[\\x00-\\x7F+]{0,255}\"\\}`
+ **BackupS3KeyName (Optional):**
+ Description: (Optional) If `Action` is set to `Restore`, this specifies the Amazon S3 key the automation will use to try to restore the target Amazon EC2 instance configuration. The Amazon S3 key typically follows this format: `{year}/{month}/{day}/{hour}/{minute}/{automation_execution_id}.json`. The key can be obtained from the output of a previous containment automation execution.
+ Type: String
+ Allowed Pattern: `^[a-zA-Z0-9\\.\\-_\\\\!*'()/]{0,1024}$`
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **ValidateRequiredInputs**
Validates that all required inputs are provided.
+ **AssertInstanceIsNotTerminated**
Checks if the target Amazon EC2 Instance is not in terminated (deleted).
+ **GetAutoScalingInstanceInfo**
Gets the Amazon EC2 instance lifecycle and group name if the target Amazon EC2 instance is part of an Auto Scaling group.
+ **CheckBackupS3BucketName**
Checks if the target Amazon S3 bucket potentially grants `read` or `write` public access to its objects. A new Amazon S3 bucket is created if the `BackupS3BucketName` bucket doesn't exist.
+ **BranchOnActionAndMode**
Branches the automation based on the input parameters `Action` and `DryRun`.
+ **BranchOnAutoScalingGroupMembership**
Branches the automation based on if the target Amazon EC2 Instance is part of Auto Scaling group and its lifecycle state.
+ **DescribeAutoScalingGroups**
Gets and stores the associated Amazon EC2 Auto Scaling group configuration.
+ **ModifyAutoScalingGroup**
Modifies the associated Amazon EC2 Auto Scaling group configuration for the containment actions, setting the Amazon EC2 instance to the `Standby` state and adjusting the Auto Scaling group `MinSize` capacity.
+ **BackupInstanceSecurityGroups**
Gets and stores the configuration of the target Amazon EC2 Instance security groups.
+ **CreateAllAccessSecurityGroup**
Creates a temporary security group allowing all ingress traffic that replaces the target Amazon EC2 Instance's security groups.
+ **CreateContainmentSecurityGroup**
Creates a restrictive containment security group with the specified ingress and egress rules, and replaces the temporary all-access group with it.
+ **BranchOnCreateAMIBackup**
Branches the automation based on the `CreateAMIBackup` input parameter.
+ **AssertSourceInstanceRootVolumeIsEbs**
Checks if the target Amazon EC2 Instance root volume is Amazon EBS.
+ **CreateImage**
Creates an AMI of the target Amazon EC2 Instance.
+ **RestoreInstanceConfiguration**
Restores the target Amazon EC2 Instance configuration from the backup.
+ **ReportContain**
Outputs dry run details for the containment actions.
+ **ReportRestore**
Outputs dry run details for the restoring actions.
+ **ReportRestoreFailure**
Provides instructions to restore the target Amazon EC2 Instance original configuration during a restore workflow failure scenario.
+ **ReportContainmentFailure**
Provides instructions to restore the target Amazon EC2 Instance original configuration during a containment workflow failure scenario.
+ **FinalOutput**
Outputs the details of the containment actions.
1. After the execution completes, review the Outputs section for the detailed results of the execution:
+ **FinalOutput.Output**
Outputs the details of the containment actions performed by this runbook when `DryRun` is set to False.
+ **RestoreInstanceConfiguration.Output**
Outputs the restore actions performed by this runbook when `DryRun` is set to False.
+ **ReportContain.Output**
Outputs the details of the containment actions performed by this runbook when `DryRun` is set to True.
+ **ReportRestore.Output**
Outputs the details of the restore actions performed by this runbook when `DryRun` is set to True.
+ **ReportContainmentFailure.Output**
Provides instructions to restore the target Amazon EC2 Instance original configuration during a containment workflow failure scenario.
+ **ReportRestoreFailure.Output**
Provides instructions to restore the target Amazon EC2 Instance original configuration during a restore workflow failure scenario.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ContainEC2Instance)
+ [Running a simple automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSSupport-CopyEC2Instance`
**Description**
The `AWSSupport-CopyEC2Instance` runbook provides an automated solution for the procedure outlined in the Knowledge Center article [How do I move my EC2 instance to another subnet, Availability Zone, or VPC?](https://aws.amazon.com/premiumsupport/knowledge-center/move-ec2-instance/) The automation branches depending on the values you specify for the `Region` and `SubnetId` parameters.
If you specify a value for the `SubnetId` parameter but not a value for the `Region` parameter, the automation creates an Amazon Machine Image (AMI) of the target instance and launches a new instance from the AMI in the subnet you specified.
If you specify a value for the `SubnetId` parameter and the `Region` parameter, the automation creates an AMI of the target instance, copies the AMI to the AWS Region you specified, and launches a new instance from the AMI in the subnet you specified.
If you specify a value for the `Region` parameter but not a value for the `SubnetId` parameter, the automation creates an AMI of the target instance, copies the AMI to the Region you specified, and launches a new instance from the AMI in the default subnet of your virtual private cloud (VPC) in the destination Region.
If no value is specified for either the `Region` or `SubnetId` parameters, the automation creates an AMI of the target instance, and launches a new instance from the AMI in the default subnet of your VPC.
To copy an AMI to a different Region, you must provide a value for the `AutomationAssumeRole` parameter. If the automation times out during the `waitForAvailableDestinationAmi` step, the AMI might still be copying. If this is the case, you can wait for the copy to complete and launch the instance manually.
Before running this automation, note the following:
+ AMIs are based on Amazon Elastic Block Store (Amazon EBS) snapshots. For large file systems without a previous snapshot, AMI creation can take several hours. To decrease the AMI creation time, create an Amazon EBS snapshot before you create the AMI.
+ Creating an AMI doesn't create a snapshot for instance store volumes on the instance. For information about backing up instance store volumes to Amazon EBS, see [How do I back up an instance store volume on my Amazon EC2 instance to Amazon EBS?](https://aws.amazon.com/premiumsupport/knowledge-center/back-up-instance-store-ebs/)
+ The new Amazon EC2 instance has a different private IPv4 or public IPv6 IP address. You must update all references to the old IP addresses (for example, in DNS entries) with the new IP addresses that are assigned to the new instance. If you're using an Elastic IP address on your source instance, be sure to attach it to the new instance.
+ Domain security identifier (SID) conflict issues can occur when the copy launches and tries to contact the domain. Before you capture the AMI, use Sysprep or remove the domain-joined instance from the domain to prevent conflict issues. For more information, see [How can I use Sysprep to create and install custom reusable Windows AMIs?](https://aws.amazon.com/premiumsupport/knowledge-center/sysprep-create-install-ec2-windows-amis/)
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-CopyEC2Instance)
**Important**
We do not recommend using this runbook to copy Microsoft Active Directory Domain Controller instances.
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the instance that you want to copy.
+ KeyPair
Type: String
Description: (Optional) The key pair you want to associate with the new copied instance. If you're copying the instance to a different Region, make sure the key pair exists in the specified Region.
+ Region
Type: String
Description: (Optional) The Region you want to copy the instance to. If you specify a value for this parameter, but do not specify values for the `SubnetId` and `SecurityGroupIds` parameters, the automation attempts to launch the instance in the default VPC with the default security group. If EC2-Classic is enabled in the destination Region, the launch will fail.
+ SubnetId
Type: String
Description: (Optional) The ID of the subnet you want to copy the instance to. If EC2-Classic is enabled in the destination Region, you must provide a value for this parameter.
+ InstanceType
Type: String
Description: (Optional) The instance type the copied instance should be launched as. If you do not specify a value for this parameter, the source instance type is used. If the source instance type is not supported in the Region the instance is being copied to, the automation fails.
+ SecurityGroupIds
Type: String
Description: (Optional) A comma-separated list of security group IDs you want to associate with the copied instance. If you do not specify a value for this parameter, and the instance is not being copied to a different Region, the security groups associated with the source instance are used. If you're copying the instance to a different Region, the default security group for the default VPC in the destination Region is used.
+ KeepImageSourceRegion
Type: Boolean
Valid values: true \$1 false
Default: true
Description: (Optional) If you specify `true` for this parameter, the automation does not delete the AMI of the source instance. If you specify `false` for this parameter, the automation deregisters the AMI and deletes the associated snapshots.
+ KeepImageDestinationRegion
Type: Boolean
Valid values: true \$1 false
Default: true
Description: (Optional) If you specify `true` for this parameter, the automation does not delete the AMI that is copied to the Region you specified. If you specify `false` for this parameter, the automation deregisters the AMI and deletes the associated snapshots.
+ NoRebootInstanceBeforeTakingImage
Type: Boolean
Valid values: true \$1 false
Default: false
Description: (Optional) If you specify `true` for this parameter, the source instance will not be restarted before creating the AMI. When this option is used, file system integrity on the created image can't be guaranteed.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:CreateImage`
+ `ec2:DeleteSnapshot`
+ `ec2:DeregisterImage`
+ `ec2:DescribeInstances`
+ `ec2:DescribeImages`
+ `ec2:RunInstances`
If you're copying the instance to a different Region, you will also need the following permissions.
+ `ec2:CopyImage`
**Document Steps**
+ describeOriginalInstanceDetails - Gathers details from the instance to be copied.
+ assertRootVolumeIsEbs - Checks if the root volume device type is `ebs`, and if not, ends the automation.
+ evalInputParameters - Evaluates the values provided for the input parameters.
+ createLocalAmi - Creates an AMI of the source instance.
+ tagLocalAmi - Tags the AMI created in the previous step.
+ branchAssertRegionIsSame - Branches based on whether the instance is being copied within the same Region or to a different Region.
+ branchAssertSameRegionWithKeyPair - Branches based on whether a value was provided for the `KeyPair` parameter for an instance that's being copied within the same Region.
+ sameRegionLaunchInstanceWithKeyPair - Launches an Amazon EC2 instance from the AMI of the source instance in the same subnet or the subnet you specify using the key pair that you specified.
+ sameRegionLaunchInstanceWithoutKeyPair - Launches an Amazon EC2 instance from the AMI of the source instance in the same subnet or the subnet you specify without a key pair.
+ copyAmiToRegion - Copies the AMI to the destination Region.
+ waitForAvailableDestinationAmi - Waits for the copied AMI state to become `available`.
+ destinationRegionLaunchInstance - Launches an Amazon EC2 Instance using the copied AMI.
+ branchAssertDestinationAmiToDelete - Branches based on the value you provided for the `KeepImageDestinationRegion` parameter.
+ deregisterDestinationAmiAndDeleteSnapshots - Deregisters the copied AMI and deletes associated snapshots.
+ branchAssertSourceAmiTodelete - Branches based on the value you provided for the `KeepImageSourceRegion` parameter.
+ deregisterSourceAmiAndDeleteSnapshots - Deregisters the AMI created from the source instance and deletes associated snapshots.
+ sleep - Sleeps the automation for 2 seconds. This is a terminal step.
**Outputs**
sameRegionLaunchInstanceWithKeyPair.InstanceIds
sameRegionLaunchInstanceWithoutKeyPair.InstanceIds
destinationRegionLaunchInstance.DestinationInstanceId
# `AWSPremiumSupport-DiagnoseDiskUsageOnLinux`
**Description**
The **AWSPremiumSupport-DiagnoseDiskUsageOnLinux** runbook analyzes the target Amazon Elastic Compute Cloud (Amazon EC2) instance's Amazon Elastic Block Store (Amazon EBS) volumes to determine if they require expansion. It checks each volume's usage, file system type, and expansion history against the thresholds defined in the runbook input parameters. The script considers factors such as recent modifications, supported file systems, and AWS volume limits. It then outputs the volumes, if any, that are candidates for expansion, along with relevant details for each volume.
**How does it work?**
This runbook performs the following operations:
+ Verifies that the target instance is managed by Systems Manager and is not running Windows
+ Retrieves instance details including platform and root device type
+ Fetches the volumes used by the Amazon EC2 instance
+ Runs prechecks on Linux to analyze disk usage and determine expansion candidates
+ Outputs volumes that are candidates for expansion with relevant details
**Important**
Access to `AWSPremiumSupport-*` runbooks requires a Business \$1 Support, Enterprise Support or Unified Operations Subscription. For more information, see [Compare AWS Support Plans](https://aws.amazon.com/premiumsupport/plans/).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSPremiumSupport-DiagnoseDiskUsageOnLinux)
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ ssm:DescribeInstanceInformation
+ ec2:DescribeInstances
+ ec2:DescribeVolumes
+ ssm:SendCommand
+ ssm:ListCommandInvocations
Example Policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeInstanceInformation",
"ec2:DescribeInstances",
"ec2:DescribeVolumes",
"ssm:SendCommand",
"ssm:ListCommandInvocations"
],
"Resource": "*"
}
]
}
```
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSPremiumSupport-DiagnoseDiskUsageOnLinux/description](https://console.aws.amazon.com/systems-manager/documents/AWSPremiumSupport-DiagnoseDiskUsageOnLinux/description) in Systems Manager under Documents.
1. Select **Execute automation.**
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
+ Description: (Optional) The Amazon Resource Name (ARN) of the 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.
+ Type: `AWS::IAM::Role::Arn`
+ **InstanceId (Required):**
+ Description: (Required) ID of your Amazon EC2 instance.
+ Type: `String`
+ Allow Pattern: `^i-[0-9a-f]{8,17}$`
+ **VolumeExpansionUsageTrigger (Required):**
+ Description: (Required) Minimum usage of partition space required to trigger extension (in percentage).
+ Type: `String`
+ Allow Pattern: `^[0-9]{1,2}$`
+ **VolumeExpansionCapSize (Required):**
+ Description: (Required) Maximum size that the Amazon EBS Volume will be increased to (in GiB).
+ Type: `String`
+ Allow Pattern: `^[0-9]{1,4}$`
+ **VolumeExpansionGibIncrease (Required):**
+ Description: (Required) Increase in GiB of the volume. The biggest net increase between `VolumeExpansionGibIncrease` and `VolumeExpansionPercentageIncrease` will be used.
+ Type: `String`
+ Allow Pattern: `^[0-9]{1,4}$`
+ **VolumeExpansionPercentageIncrease (Required):**
+ Description: (Required) Increase in percentage of the volume. The biggest net increase between `VolumeExpansionGibIncrease` and `VolumeExpansionPercentageIncrease` will be used.
+ Type: `String`
+ Allow Pattern: `^[0-9]{1,2}$`
1. Select **Execute**.
1. The automation initiates.
1. The document performs the following steps:
+ **AssertInstanceIsManagedInstance**:
Checks if the target instance is managed by Systems Manager.
+ **DescribeInstance**:
Describes the target Amazon EC2 instance and retrieves the instance details including `Platform`, and `RootDeviceType`.
+ **BranchOnPlatform**:
Branches on the type of platform and proceeds the execution if it's different than Windows.
+ **DescribeVolumes**:
Fetches the volumes used by the Amazon EC2 Instance.
+ **RunPreChecksOnLinux**:
Run the checks against the volumes gathered in the previous step.
1. After completed, review the **Outputs** section for the detailed results of the execution.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSPremiumSupport-DiagnoseDiskUsageOnLinux/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSSupport-EnableWindowsEC2SerialConsole`
**Description**
The runbook `AWSSupport-EnableWindowsEC2SerialConsole` helps you enable Amazon EC2 Serial Console, Special Admin Console (SAC), and boot menu on your Amazon EC2 Windows instance. With Amazon Elastic Compute Cloud (Amazon EC2) Serial Console feature, you have access to your Amazon EC2 instance's serial port to troubleshoot boot, network configuration, and other issues. The runbook automates the steps required to enable the feature on instances in running state and managed by AWS Systems Manager, as well as ones in stopped state or not managed by AWS Systems Manager.
**How does it work?**
The `AWSSupport-EnableWindowsEC2SerialConsole` automation runbook helps to enable SAC and boot menu on Amazon EC2 instances running Microsoft Windows Server. For instances in running state and managed by AWS Systems Manager, the runbook runs an AWS Systems Manager Run Command PowerShell script to enable SAC and boot menu. For instances in stopped state or not managed by AWS Systems Manager, the runbook uses the [AWSSupport-StartEC2RescueWorkflow](https://docs.aws.amazon.com//systems-manager-automation-runbooks/latest/userguide/automation-awssupport-startec2rescueworkflow.html) to create a temporary Amazon EC2 instance to perform the required changes offline.
For more information see [Amazon EC2 Serial Console for Windows instances.](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/ec2-serial-console.html)
**Important**
If you enable SAC on an instance, the Amazon EC2 services that rely on password retrieval will not work from the Amazon EC2 console. For more information, see [Use SAC to troubleshoot your Windows instance.](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/troubleshooting-sac.html)
To configure access to the serial console, you must grant serial console access at the account level and then configure AWS Identity and Access Management (IAM) policies to grant access to your users. You must also configure a password-based user on every instance so that your users can use the serial console for troubleshooting. For more information see [Configure access to the Amazon EC2 Serial Console.](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/configure-access-to-serial-console.html)
To see if the serial console is enabled on your account see [View account access status to the serial console.](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/configure-access-to-serial-console.html#sc-view-account-access)
Serial console access is only supported on virtualized instances built on the [Nitro System.](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-types.html#nitro-instance-types)
For more information, see the Amazon EC2 Serial Console [Prerequisites.](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/ec2-serial-console-prerequisites.html)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingInstances",
"ec2:GetSerialConsoleAccessStatus",
"ec2:Describe*",
"ec2:createTags",
"ec2:createImage",
"ssm:DescribeAutomationExecutions",
"ssm:DescribeInstanceInformation",
"ssm:GetAutomationExecution",
"ssm:ListCommandInvocations",
"ssm:ListCommands"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume",
"ec2:ModifyInstanceAttribute",
"ec2:RebootInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"iam:GetInstanceProfile",
"ssm:GetParameters",
"ssm:SendCommand",
"ssm:StartAutomationExecution"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/i-02573cafcfEXAMPLE",
"arn:aws:ec2:us-east-1:111122223333:volume/vol-049df61146EXAMPLE",
"arn:aws:iam::111122223333:instance-profile/instance-profile-name",
"arn:aws:ssm:us-east-1:111122223333:parameter/aws/service/*",
"arn:aws:ssm:us-east-1:*:document/AWSSupport-StartEC2RescueWorkflow",
"arn:aws:ssm:us-east-1:*:document/AWS-ConfigureAWSPackage",
"arn:aws:ssm:us-east-1:*:document/AWS-RunPowerShellScript",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
},
{
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aws:RequestTag/Name": "AWSSupport-EC2Rescue: *"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AWSSupport-EC2Rescue-AutomationExecution",
"Name"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"cloudformation:DeleteStack",
"cloudformation:DescribeStackEvents",
"cloudformation:DescribeStackResource",
"cloudformation:DescribeStacks",
"ec2:AttachVolume",
"ec2:DetachVolume",
"ec2:RebootInstances",
"ec2:StopInstances",
"ec2:TerminateInstances",
"ssm:SendCommand"
],
"Resource": "*",
"Condition": {
"StringLike": {
"aws:ResourceTag/Name": "AWSSupport-EC2Rescue: *"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateLaunchTemplate",
"ec2:DeleteLaunchTemplate",
"ec2:RunInstances"
],
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": [
"cloudformation.amazonaws.com"
]
}
}
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "*",
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com",
"ec2.amazonaws.com"
]
}
}
}
]
}
```
------
**Instructions**
Follow these steps to configure the automation:
1. Navigate to the `AWSSupport-EnableWindowsEC2SerialConsole` in the AWS Systems Manager console.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **InstanceId: (Required)**
The ID of the Amazon EC2 instance that you want to enable Amazon EC2 serial console, (SAC), and boot menu.
+ **AutomationAssumeRole: (Optional)**
The Amazon Resource Name (ARN) of the 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 who starts this runbook.
+ **HelperInstanceType: (Conditional)**
The type of Amazon EC2 instance that the runbook provisions to configure Amazon EC2 serial console for an offline instance.
+ **HelperInstanceProfileName: (Conditional)**
The name of an existing IAM instance profile for the helper instance. If you are enabling SAC and boot menu on an instance that is in stopped state or not managed by AWS Systems Manager, this is required. If an IAM instance profile is not specified, the automation creates one on your behalf.
+ **SubnetId: (Conditional)**
The subnet ID for a helper instance. By default, it uses the the same subnet where the provided instance resides.
**Important**
If you provide a custom subnet, it must be in the same Availability Zone as InstanceId, and it must allow access to the Systems Manager endpoints. This is only required if the target instance is in stopped state or is not managed by AWS Systems Manager.
+ **CreateInstanceBackupBeforeScriptExecution: (Optional)**
Specify True to create an Amazon Machine Images (AMI) backup of the Amazon EC2 instance before enabling SAC and boot menu. The AMI will persist after the automation completes. It is your responsibility to secure access to the AMI or delete it.
+ **BackupAmazonMachineImagePrefix: (Conditional)**
A prefix for the Amazon Machine Image (AMI) that is created if the `CreateInstanceBackupBeforeScriptExecution` parameter is set to `True`.
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **CheckIfEc2SerialConsoleAccessEnabled:**
Checks if Amazon EC2 Serial Console access is enabled at the account level. Note: Access to the serial console is not available by default. For more information see [Configure access to the Amazon EC2 Serial Console.](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/configure-access-to-serial-console.html#sc-grant-account-access)
+ **CheckIfEc2InstanceIsWindows:**
Asserts if the target instance platform is Windows.
+ **GetInstanceType:**
Retrieves the instance type of the target instance.
+ CheckIfInstanceTypeIsNitro:****
Checks if the instance type hypervisor is Nitro-based. Serial Console Access is only supported on virtualized instances built on the Nitro System.
+ **CheckIfInstanceIsInAutoScalingGroup:**
Checks if the Amazon EC2 instance is part of an Amazon EC2 Auto Scaling group by calling the `DescribeAutoScalingInstances` API. If the instance is part of an Amazon EC2 Auto Scaling group, it ensures that the Porting Assistant for .NET instance is in Standby lifecycle state.
+ **WaitForEc2InstanceStateStablized:**
Waits for the instance to be in running or stopped state.
+ **GetEc2InstanceState:**
Gets the current state of the instance.
+ **BranchOnEc2InstanceState:**
Branches based on the instance state retrieved in the previous step. If that instance state is running, it goes to the `CheckIfEc2InstanceIsManagedBySSM` step and if not, it goes to the `CheckIfHelperInstanceProfileIsProvided` step.
+ **CheckIfEc2InstanceIsManagedBySSM:**
Checks if the instance is managed by AWS Systems Manager. If managed, the runbook enables SAC and boot menu using a PowerShell Run Command.
+ **BranchOnPreEC2RescueBackup:**
Branches based on the `CreateInstanceBackupBeforeScriptExecution` input parameter.
+ **CreateAmazonMachineImageBackup:**
Creates an AMI backup of the instance.
+ **EnableSACAndBootMenu:**
Enables SAC and boot menu by running a PowerShell Run Command script.
+ **RebootInstance:**
Reboots the Amazon EC2 instance to apply the configuration. This is the final step if the instance is online and is managed by AWS Systems Manager.
+ **CheckIfHelperInstanceProfileIsProvided:**
Checks if the `HelperInstanceProfileName` specified exists before enabling SAC and boot menu offline using a temporary Amazon EC2 instance.
+ **RunAutomationToInjectOfflineScriptForEnablingSACAndBootMenu:**
Runs the `AWSSupport-StartEC2RescueWorkflow` to enable SAC and boot menu when the instance is in stopped state or not managed by AWS Systems Manager.
+ **GetExecutionDetails:**
Retrieves Image ID of backup and offline script output.
1. After completed, review the Outputs section for the detailed results of the execution:
+ **EnableSACAndBootMenu.Output:**
Output of the command execution in the `EnableSACAndBootMenu` step.
+ **GetExecutionDetails.OfflineScriptOutput:**
Output of the offline script executed in the `RunAutomationToInjectOfflineScriptForEnablingSACAndBootMenu` step.
+ **GetExecutionDetails.BackupBeforeScriptExecution:**
Image ID of the AMI backup taken if `CreateInstanceBackupBeforeScriptExecution` input parameter is True.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-EnableWindowsEC2SerialConsole)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows landing page](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSPremiumSupport-ExtendVolumesOnWindows`
**Description**
The `AWSPremiumSupport-ExtendVolumesOnWindows` runbook extends the Amazon Elastic Block Store (Amazon EBS) volumes, their partitions, and filesystems on a target Amazon Elastic Compute Cloud (Amazon EC2) instance.
**Important considerations**
**Operation Impact and Volume States**: Amazon EBS volume modifications occur in three phases: `modifying`, `optimizing`, and `completed`. This automation proceeds with filesystem extension when the volume reaches the `optimizing` state. During the `optimizing` state you might experience temporary performance impact and potential filesystem-level disruptions during partition resizing. You can [Monitor the progress of Amazon EBS volume modifications](https://docs.aws.amazon.com//ebs/latest/userguide/monitoring-volume-modifications.html).
**Cost and Limitations**: Increasing an Amazon EBS volume size will result in higher monthly storage costs. For more information, see the [Amazon EBS Pricing](https://aws.amazon.com/ebs/pricing). The backup AMI and associated snapshots created by this runbook will incur additional charges based on their size and the length of time that you keep them. For some volume types, if you need to maintain the same IOPS per GB ratio after expansion, you may need to modify the provisioned IOPS.
**Backup and Recovery**: The runbook creates a backup AMI before making any changes to the volumes. The AMI and associated snapshots are not automatically removed from your account. You should manually remove these backups if no longer required. In case of failure, volumes can be recovered from the snapshots of the associated AMI as described in [Replace an Amazon EBS volume using a snapshot](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/ebs-restoring-volume.html).
**How does it work?**
This runbook performs the following operations:
+ Verifies that the target instance is managed by Systems Manager and is running Windows Server
+ Ensures there is only one execution of this runbook targeting the current Amazon EC2 instance
+ Creates a backup Amazon Machine Image (AMI) from the target instance
+ Extends the Amazon EBS volumes that were specified for expansion
+ Extends the filesystems on the target instance using PowerShell commands
**Important**
Access to `AWSPremiumSupport-*` runbooks requires a Business \$1 Support, Enterprise Support or Unified Operations Subscription. For more information, see [Compare AWS Support Plans](https://aws.amazon.com/premiumsupport/plans/).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSPremiumSupport-ExtendVolumesOnWindows)
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeInstances`
+ `ec2:CreateImage`
+ `ec2:DescribeImages`
+ `ec2:DescribeVolumes`
+ `ec2:ModifyVolume`
+ `ssm:SendCommand`
+ `ssm:ListCommandInvocations`
+ `ssm:DescribeInstanceInformation`
Example IAM policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:CreateImage",
"ec2:DescribeImages",
"ec2:DescribeVolumes",
"ec2:ModifyVolume",
"ssm:SendCommand",
"ssm:DescribeInstanceInformation",
"ssm:ListCommandInvocations"
],
"Resource": "*"
}
]
}
```
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSPremiumSupport-ExtendVolumesOnWindows/description](https://console.aws.amazon.com/systems-manager/documents/AWSPremiumSupport-ExtendVolumesOnWindows/description) in Systems Manager under Documents.
1. Select **Execute automation.**
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
+ Description: (Optional) The Amazon Resource Name (ARN) of the 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.
+ Type: `AWS::IAM::Role::Arn`
+ **InstanceId (Required):**
+ Description: (Required) The ID of the Amazon EC2 instance.
+ Type: `String`
+ Allow Pattern: `^i-[0-9a-f]{8,17}$`
+ **VolumeExpansionCapSize (Required):**
+ Description: (Required) Maximum size (in GiB) that the Amazon EBS volumes will be increased.
+ Type: `String`
+ Allow Pattern: `^[0-9]{1,4}$`
+ **DiagnosticResults (Required):**
+ Description: (Required) The results of the prechecks script from the `DiagnoseDiskUsage` document, formatted as a one-line CSV. The string starts with `EXTEND;` followed by comma-separated volume information for each volume, with volumes separated by semicolons. Each volume's information includes: Volume ID, Drive letter, Extend flag (1 to extend, 0 to skip), New size in GB, AWS region, and Reason/Action.
+ Type: `String`
+ Allow Pattern: `^EXTEND;[0-9a-zA-Z\\.;_%:\\-\/,\\s]{7,5400}$`
1. Select **Execute**.
1. The automation initiates.
1. The document performs the following steps:
+ **AssertInstanceIsManagedInstance**:
Verifies that the target instance is managed by Systems Manager.
+ **DescribeInstance**:
Retrieves the Platform information of the target Amazon EC2 instance.
+ **BranchOnPlatform**:
Confirms that the target Amazon EC2 instance platform is Windows Server.
+ **CheckConcurrency**:
Ensures there is only one execution of this runbook targeting the current Amazon EC2 instance.
+ **CreateImage**:
Creates a backup Amazon Machine Image (AMI) from the target instance.
+ **WaitUntilImageReady**:
Waits for the Amazon Machine Image (AMI) to complete creation and reach the `available` state.
+ **ExtendEBSVolume**:
Extends the Amazon EBS volumes of the target instance that were specified for expansion.
+ **DescribeVolumes**:
Describes the Amazon EBS volumes of the target instance that were specified for expansion.
+ **ExtendFilesystem**:
Extends the filesystems of the target instance using PowerShell commands.
1. After completion, review the **Outputs** section for the detailed results of the execution.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSPremiumSupport-ExtendVolumesOnWindows/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
+ [Request Amazon EBS volume modifications](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/requesting-ebs-volume-modifications.html)
# `AWSSupport-ExecuteEC2Rescue`
**Description**
This runbook uses the EC2Rescue tool to troubleshoot and, where possible, repair common connectivity issues with the specified Amazon Elastic Compute Cloud (Amazon EC2) instance for Linux or Windows Server. Instances with encrypted root volumes are not supported.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ExecuteEC2Rescue)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ EC2RescueInstanceType
Type: String
Valid values: t2.small \$1 t2.medium \$1 t2.large
Default: t2.small
Description: (Required) The EC2 instance type for the EC2Rescue instance. Recommended size: `t2.small`
+ LogDestination
Type: String
Description: (Optional) Amazon 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.
+ SubnetId
Type: String
Default: CreateNewVPC
Description: (Optional) The subnet ID for the EC2Rescue instance. By default, AWS Systems Manager Automation creates a new VPC. Alternatively, use `SelectedInstanceSubnet` to use the same subnet as your instance, or specify a custom subnet ID. ``
**Important**
The subnet must be in the same Availability Zone as `UnreachableInstanceId`, and it must allow access to the SSM endpoints.
+ UnreachableInstanceId
Type: String
Description: (Required) ID of your unreachable EC2 instance.
**Important**
Systems Manager Automation stops this instance, and creates an AMI before attempting any operations. Data stored in instance store volumes will be lost. The public IP address will change if you are not using an Elastic IP address.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
You must have at least `ssm:StartAutomationExecution` and `ssm:GetAutomationExecution` to be able to read the automation output. For more information about the required permissions, see [`AWSSupport-StartEC2RescueWorkflow`](automation-awssupport-startec2rescueworkflow.md).
**Document Steps**
1. `aws:assertAwsResourceProperty` - Asserts if the provided instance is Windows Server:
1. (EC2Rescue for Windows Server) If the provided instance is a Windows Server instance:
1. `aws:executeAutomation` - Invokes `AWSSupport-StartEC2RescueWorkflow` with the EC2Rescue for Windows Server offline script.
1. `aws:executeAwsApi` - Retrieves the backup AMI ID from the nested automation.
1. `aws:executeAwsApi` - Retrieves the EC2Rescue summary from the nested automation.
1. (EC2Rescue for Linux) If the provided instance is a Linux instance:
1. `aws:executeAutomation` - Invokes `AWSSupport-StartEC2RescueWorkflow` with the EC2Rescue for Linux offline scripts
1. `aws:executeAwsApi` - Retrieves the backup AMI ID from the nested automation.
1. `aws:executeAwsApi` - Retrieves the EC2Rescue summary from the nested automation.
**Outputs**
`getEC2RescueForWindowsResult.Output`
`getWindowsBackupAmi.ImageId`
`getEC2RescueForLinuxResult.Output`
`getLinuxBackupAmi.ImageId`
# `AWSSupport-ListEC2Resources`
**Description**
The `AWSSupport-ListEC2Resources` runbook returns information about Amazon EC2 instances and related resources like Amazon Elastic Block Store (Amazon EBS) volumes, Elastic IP addresses, and Amazon EC2 Auto Scaling groups from the AWS Regions you specify. By default, the information is gathered from all Regions and is displayed in the output of the automation. Optionally, you can specify an Amazon Simple Storage Service (Amazon S3) bucket for the information to be uploaded to as a comma-separated values (.csv) file.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ListEC2Resources)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ BucketName
Type: String
Description: (Optional) The name of the S3 bucket where the information gathered is uploaded to.
+ DisplayResourceDeletionDocumentation
Type: String
Default: true
Description: (Optional) If set to `true`, the automation creates links in the output to documentation related to deleting your resources.
+ RegionsToQuery
Type: String
Default: All
Description: (Optional) The Regions you want to gather Amazon EC2 related information from.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `autoscaling:DescribeAutoScalingGroups`
+ `ec2:DescribeAddresses`
+ `ec2:DescribeImages`
+ `ec2:DescribeInstances`
+ `ec2:DescribeNetworkInterfaces`
+ `ec2:DescribeRegions`
+ `ec2:DescribeVolumes`
+ `ec2:DescribeSnapshots`
+ `elasticloadbalancing:DescribeLoadBalancers`
Additionally, to successfully upload the information gathered to the S3 bucket you specify, the `AutomationAssumeRole` requires the following actions:
+ `s3:GetBucketAcl`
+ `s3:GetBucketPolicyStatus`
+ `s3:PutObject`
**Document Steps**
+ `aws:executeAwsApi` - Gathers the Regions enabled for the account.
+ `aws:executeScript` - Confirms the Regions enabled for the account support the Regions specified in the `RegionsToQuery` parameter.
+ `aws:branch` - If no Regions are enabled for the account, the automation ends.
+ `aws:executeScript` - Lists all EC2 instances for the account and Regions you specify.
+ `aws:executeScript` - Lists all Amazon Machine Images (AMI) for the account and Regions you specify.
+ `aws:executeScript` - Lists all EBS volumes for the account and Regions you specify.
+ `aws:executeScript` - Lists all Elastic IP addresses for the account and Regions you specify.
+ `aws:executeScript` - Lists all elastic network interfaces for the account and Regions you specify.
+ `aws:executeScript` - Lists all Auto Scaling groups for the account and Regions you specify.
+ `aws:executeScript` - Lists all load balancers for the account and Regions you specify.
+ `aws:executeScript` - Uploads the information gathered to the S3 bucket specified if you provide a value for the `Bucket` parameter.
# `AWSSupport-ManageRDPSettings`
**Description**
The `AWSSupport-ManageRDPSettings` runbook allows the user to manage common Remote Desktop Protocol (RDP) settings, such as the RDP port and Network Layer Authentication (NLA). By default, the runbook reads and outputs the values of the settings.
**Important**
Changes to the RDP settings should be carefully reviewed before running this runbook.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ManageRDPSettings)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the managed instance to manage the RDP settings of.
+ NLASettingAction
Type: String
Valid values: Check \$1 Enable \$1 Disable
Default: Check
Description: (Required) An action to perform on the NLA setting: Check, Enable, Disable.
+ RDPPort
Type: String
Default: 3389
Description: (Optional) Specify the new RDP port. Used only when the action is set to Modify. The port number must be between 1025-65535. Note: After the port is changed, the RDP service is restarted.
+ RDPPortAction
Type: String
Valid values: Check \$1 Modify
Default: Check
Description: (Required) An action to apply to the RDP port.
+ RemoteConnections
Type: String
Valid values: Check \$1 Enable \$1 Disable
Default: Check
Description: (Required) An action to perform on the fDenyTSConnections setting.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
The EC2 instance receiving the command must have an IAM role with the **AmazonSSMManagedInstanceCore** Amazon managed policy attached. The user must have at least **ssm:SendCommand** to send the command to the instance, plus **ssm:GetCommandInvocation** to be able to read the command output.
**Document Steps**
`aws:runCommand` - Run the PowerShell script to change or check the RDP settings on the target instance.
**Outputs**
manageRDPSettings.Output
# `AWSSupport-ManageWindowsService`
**Description**
The `AWSSupport-ManageWindowsService` runbook enables you to stop, start, restart, pause, or disable any Windows service on the target instance.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ManageWindowsService)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the managed instance to manage the services of.
+ ServiceAction
Type: String
Valid values: Check \$1 Restart \$1 Force-Restart \$1 Start \$1 Stop \$1 Force-Stop \$1 Pause
Default: Check
Description: (Required) An action to apply to the Windows service. Note that `Force-Restart` and `Force-Stop` can be used to restart and to stop a service that has dependent services.
+ StartupType
Type: String
Valid values: Check \$1 Auto \$1 Demand \$1 Disabled \$1 DelayedAutoStart
Default: Check
Description: (Required) A startup type to apply to the Windows service.
+ WindowsServiceName
Type: String
Description: (Required) A valid Windows service name.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
It is recommended that the EC2 instance receiving the command has an IAM role with the **AmazonSSMManagedInstanceCore** Amazon managed policy attached. The user must have at least **ssm:StartAutomationExecution** and **ssm:SendCommand** to run the automation and send the command to the instance, plus **ssm:GetAutomationExecution** to be able to read the automation output.
**Document Steps**
`aws:runCommand` - Run the PowerShell script to apply the desired configuration to the Windows service on the target instance.
**Outputs**
manageWindowsService.Output
# `AWSSupport-MigrateEC2ClassicToVPC`
**Description**
The `AWSSupport-MigrateEC2ClassicToVPC` runbook migrates an Amazon Elastic Compute Cloud (Amazon EC2) instance from EC2-Classic to a virtual private cloud (VPC). This runbook supports migrating Amazon EC2 instances of the hardware virtual machine (HVM) virtualization type with Amazon Elastic Block Store (Amazon EBS) root volumes.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-MigrateEC2ClassicToVPC)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ AutomationAssumeRole
Type: String
Description: (Required) 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.
+ ApproverIAM
Type: StringList
Description: (Optional) The Amazon Resource Names (ARNs) of IAM users who can approve or deny the action. This parameter only applies if you specify the `CutOver` value for the `MigrationType` parameter.
+ DestinationSecurityGroupId
Type: StringList
Description: (Optional) The ID of the security group that you want to associate with the Amazon EC2 instance that is launched in your VPC. If you don't specify a value for this parameter, the automation creates a security group in your VPC and copies the rules from the security group in EC2-Classic. If the rules fail to copy to the new security group, the default security group of your VPC is associated with the Amazon EC2 instance.
+ DestinationSubnetId
Type: String
Description: (Optional) The ID of the subnet that you want to migrate your Amazon EC2 instance to. If you do not specify a value for this parameter, the automation randomly chooses a subnet from your VPC.
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instance that you want to migrate.
+ MigrationType
Type: String
Valid values: CutOver \$1 Test
Description: (Required) The type of migration that you want to perform.
The `CutOver` option requires approval to stop your Amazon EC2 instance that's running in EC2-Classic. After this action is approved, the Amazon EC2 instance is stopped and the automation creates an Amazon Machine Image (AMI). When the AMI status is `available`, a new Amazon EC2 instance is launched from this AMI in the `DestinationSubnetId` you specify in your VPC. If your Amazon EC2 instance that's running in EC2-Classic has an Elastic IP address attached, the instance will be moved to the newly created Amazon EC2 instance in your VPC. If the Amazon EC2 instance launching in your VPC fails to create for any reason, it is terminated and approval is requested to start your Amazon EC2 instance in EC2-Classic.
The `Test` option creates an AMI of your Amazon EC2 instance that's running in EC2-Classic without rebooting. Because the Amazon EC2 instance does not reboot, we can't guarantee the file system integrity of the created image. When the AMI status is `available`, a new Amazon EC2 instance is launched from this AMI in the `DestinationSubnetId` that you specify in your VPC. If your Amazon EC2 instance that's running in EC2-Classic has an Elastic IP address attached, the automation verifies that the `DestinationSubnetId` you specify is public. If the Amazon EC2 instance launching in your VPC fails to create for any reason, it is terminated and the automation ends.
+ SNSNotificationARNforApproval
Type: String
Description: (Optional) The ARN of the Amazon Simple Notification Service (Amazon SNS) topic that you want to send approval requests to. This parameter only applies if you specify the `CutOver` value for the `MigrationType` parameter.
+ TargetInstanceType
Type: String
Default: t2.2xlarge
Description: (Optional) The type of Amazon EC2 instance that you want to launch in your VPC. Only Xen-based instance types, such as T2, M4, or C4, are supported.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:GetDocument`
+ `ssm:ListDocumentVersions`
+ `ssm:ListDocuments`
+ `ssm:StartAutomationExecution`
+ `sns:GetTopicAttributes`
+ `sns:ListSubscriptions`
+ `sns:ListTopics`
+ `sns:Publish`
+ `ec2:AssociateAddress`
+ `ec2:AuthorizeSecurityGroupIngress`
+ `ec2:CreateImage`
+ `ec2:CreateSecurityGroup`
+ `ec2:DeleteSecurityGroup`
+ `ec2:MoveAddressToVpc`
+ `ec2:RunInstances`
+ `ec2:StopInstances`
+ `ec2:CreateTags`
+ `ec2:DescribeAddresses`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DescribeRouteTables`
+ `ec2:DescribeSecurityGroupReferences`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeSubnets`
+ `ec2:DescribeTags`
+ `ec2:DescribeVpcs`
+ `ec2:DescribeInstanceTypes`
+ `ec2:DescribeImages`
**Document Steps**
+ `aws:executeAwsApi` - Gathers details about the Amazon EC2 instance that you specify in the `InstanceId` parameter.
+ `aws:assertAwsResourceProperty` - Confirms the instance type that you specify in the `TargetInstanceType` parameter is Xen-based.
+ `aws:assertAwsResourceProperty` - Confirms the Amazon EC2 instance that you specify in the `InstanceId` parameter is of the HVM virtualization type.
+ `aws:assertAwsResourceProperty` - Confirms the Amazon EC2 instance that you specify in the `InstanceId` parameter has an Amazon EBS root volume.
+ `aws:executeScript` - Creates a security group as needed depending on the value that you specify for the `DestinationSecurityGroupId` parameter.
+ `aws:branch` - Branches based on the value that you specify in the `DestinationSubnetId` parameter.
+ `aws:executeAwsApi` - Identifies the default VPC in the AWS Region where you run this automation.
+ `aws:executeAwsApi` - Randomly chooses the ID of a subnet located in the default VPC.
+ `aws:createImage` - Creates an AMI without rebooting the Amazon EC2 instance.
+ `aws:branch` - Branches based on the value that you specify for the `MigrationType` parameter.
+ `aws:branch` - Branches based on the value that you specify for the `DestinationSubnetId` parameter.
+ `aws:runInstances` - Launches a new instance from the AMI created without rebooting the Amazon EC2 instance in EC2-Classic.
+ `aws:changeInstanceState` - Terminates the newly launched Amazon EC2 instance if the previous step fails for any reason.
+ `aws:runInstances` - Launches a new instance from the AMI created without rebooting the Amazon EC2 instance in EC2-Classic in the `DestinationSubnetId` if provided.
+ `aws:changeInstanceState` - Terminates the newly launched Amazon EC2 instance if the previous step fails for any reason.
+ `aws:assertAwsResourceProperty` - Confirms the stop behavior for the Amazon EC2 instance running in EC2-Classic.
+ `aws:approve` - Waits for approval to stop the Amazon EC2 instance.
+ `aws:changeInstanceState` - Stops the Amazon EC2 instance running in EC2-Classic.
+ `aws:changeInstanceState` - Force stops the Amazon EC2 instance running in EC2-Classic if needed.
+ `aws:createImage` - Creates an AMI of the Amazon EC2 instance after it has stopped.
+ `aws:branch` - Branches based on the value specified for the `DestinationSubnetId` parameter.
+ `aws:runInstances` - Launches a new instance from the AMI created of the stopped Amazon EC2 instance in EC2-Classic.
+ `aws:approve` - Waits for approval to terminate the newly launched instance and starts the Amazon EC2 instance in EC2-Classic if the previous step fails for any reason.
+ `aws:changeInstanceState` - Terminates the newly launched Amazon EC2 instance.
+ `aws:runInstances` - Launches a new instance from the AMI created of the stopped Amazon EC2 instance in EC2-Classic from the `DestinationSubnetId` parameter.
+ `aws:approve` - Waits for approval to terminate the newly launched instance and starts the Amazon EC2 instance in EC2-Classic if the previous step fails for any reason.
+ `aws:changeInstanceState` - Terminates the newly launched Amazon EC2 instance.
+ `aws:changeInstanceState` - Starts the Amazon EC2 instance that was stopped in EC2-Classic.
+ `aws:branch` - Branches based on whether the Amazon EC2 instance has a public IP address.
+ `aws:executeAwsApi` - Verifies whether the public IP address is an Elastic IP address.
+ `aws:branch` - Branches based on the value that you specify in the `MigrationType` parameter.
+ `aws:executeAwsApi` - Moves the Elastic IP address to your VPC.
+ `aws:executeAwsApi` - Gathers the allocation ID of the Elastic IP address that was moved to your VPC.
+ `aws:branch` - Branches based on which subnet the Amazon EC2 instance running in your VPC was launched.
+ `aws:executeAwsApi` - Attaches the Elastic IP address to the newly launched instance in your VPC.
+ `aws:executeScript` - Confirms the subnet your newly launched Amazon EC2 instance running in your VPC is public.
**Outputs**
g`etInstanceProperties.virtualizationType` - The virtualization type of the Amazon EC2 instance running in EC2-Classic.
`getInstanceProperties.rootDeviceType` - The root device type of the Amazon EC2 instance running in EC2-Classic.
`createAMIWithoutReboot.ImageId` - The ID of the AMI created without rebooting the Amazon EC2 instance running in EC2-Classic.
`getDefaultVPC.VpcId` - The ID of the default VPC where the new Amazon EC2 instance is launched if a value for the `DestinationSubnetId` parameter is not provided.
`getSubnetIdinDefaultVPC.subnetIdFromDefaultVpc` - The ID of the subnet in the default VPC where the new Amazon EC2 instance is launched if a value for the `DestinationSubnetId` parameter is not provided.
`launchTestInstanceDefaultVPC.InstanceIds` - The ID of the newly launched Amazon EC2 instance in your default VPC during the `Test` migration type.
`launchTestInstanceProvidedSubnet.InstanceIds` - The ID of the newly launched Amazon EC2 instance in the `DestinationSubnetId` that you specified during the `Test` migration type.
`createAMIAfterStoppingInstance.ImageId` - The ID of the AMI created after stopping the Amazon EC2 instance running in EC2-Classic.
`launchCutOverInstanceProvidedSubnet.InstanceIds` - The ID of the newly launched Amazon EC2 instance in the `DestinationSubnetId` that you specified during the `CutOver` migration type.
`launchCutOverInstanceDefaultVPC.InstanceIds` - The ID of the newly launched Amazon EC2 instance in your default VPC during the `CutOver` migration type.
`verifySubnetIsPublicTestDefaultVPC.IsSubnetPublic` - Whether the subnet chosen by the automation in your default VPC is public.
`verifySubnetIsPublicTestProvidedSubnet.IsSubnetPublic` - Whether the subnet you specified in the `DestinationSubnetId` is public.
# `AWSSupport-MigrateXenToNitroLinux`
**Description**
The `AWSSupport-MigrateXenToNitroLinux` runbook clones, prepares, and migrates an Amazon Elastic Compute Cloud (Amazon EC2) Linux Xen instance to a [Nitro instance type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances). This runbook provide two options for operation types:
+ `Clone&Migrate` – This option’s workflow consists of the **Preliminary Checks**, **Testing**, and **Clone&Migrate** phases. The workflow is run using the `AWSSupport-CloneXenEC2InstanceAndMigrateToNitro` runbook.
+ `FullMigration` – This option runs the `Clone&Migrate` workflow and then performs the additional step of **Replace root Amazon EBS volumes**.
**Important**
Using this runbook incurs costs to your account for the running time of Amazon EC2 instances, creation of Amazon Elastic Block Store (Amazon EBS) volumes, and AMIs. For more details, see [ Amazon EC2 Pricing](https://aws.amazon.com/ec2/pricing/) and [Amazon EBS Pricing](https://aws.amazon.com/ebs/pricing/).
**Preliminary checks**
The automation performs the following preliminary checks before continuing with the migration. If any of the checks fail, the automation ends. This phase is only part of the `Clone&Migrate` workflow.
+ Checks if the target instance is already a Nitro instance type.
+ Checks if the Spot Instances purchasing option was used for the target instance.
+ Checks if instance store volumes are attached to the target instance.
+ Verifies the target instance operating system (OS) is Linux.
+ Checks if the target instance is a part of an Amazon EC2 Auto Scaling group. If it is part of an Auto Scaling group, the automation verifies that the instance is in the `standby` state.
+ Verifies that the instance is managed by AWS Systems Manager.
**Testing**
The automation creates an Amazon Machine Image (AMI) from the target instance and launches a test instance from the newly created AMI. This phase is part of only the `Clone&Migrate` workflow.
If the test instance passes all status checks, the automation pauses and approval from the designated principals is requested through Amazon Simple Notification Service (Amazon SNS) notification. If approval is provided, the automation terminates the test instance, stops the target instance, and continues with the migration, while the newly created AMI is deregistered at the end of the `Clone&Migrate` workflow.
**Note**
Before providing approval, we recommend verifying that all applications running on the target instance have been closed gracefully.
**Clone and Migrate**
The automation creates another AMI from the target instance, and launches a new instance to change to a Nitro instance type. The automation completes the following prerequisites before continuing with the migration. If any of the checks fail, the automation ends. This phase is also only part of the `Clone&Migrate` workflow.
+ Turns on the enhanced networking (ENA) attribute.
+ Installs the latest version of ENA drivers if they're not already installed, or updates the ENA drivers version to the latest version. To ensure maximum network performance, updating to the latest ENA driver version is required if the Nitro instance type is the 6th generation.
+ Verifies that the NVMe module is installed. If the module is installed, the automation verifies that the module is loaded in `initramfs`.
+ Analyzes `/etc/fstab` and replaces entries with block device names (`/dev/sd*` or `/dev/xvd*`) with their respective UUIDs. Before modifying the configuration, the automation creates a backup of the file at the path `/etc/fstab*`.
+ Turns off predictable interface naming by adding the `net.ifnames=0` option to the `GRUB_CMDLINE_LINUX` line in the `/etc/default/grub` file if it exists, or to the kernel in `/boot/grub/menu.lst`.
+ Removes the `/etc/udev/rules.d/70-persistent-net.rules` file if it exists. Before removing the file, the automation creates a backup of the file at the path `/etc/udev/rules.d/`.
After verifying all requirements, the instance type is changed to the Nitro instance type that you specify. The automation waits for the newly created instance to pass all status checks after starting as a Nitro instance type. The automation then waits for approval from the designated principals to create an AMI of the successfully launched Nitro instance. If approval is denied, the automation ends, leaving the newly created instance running, and the target instance remains stopped.
**Replace root Amazon EBS Volume**
If you choose `FullMigration` as the `OperationType`, the automation migrates the target Amazon EC2 instance to the Nitro instance type that you specify. Automation requests approval from designated principals to replace the root Amazon EBS volume of the target Amazon EC2 instance with the cloned Amazon EC2 instance's root volume. After the migration is successful, the cloned Amazon EC2 instance is terminated. If the automation fails, the original Amazon EBS root volume is attached to the target Amazon EC2 instance. If the root Amazon EBS volume attached to the target Amazon EC2 instance has tags with the `aws:` prefix applied, the `FullMigration` operation isn't supported.
**Before you begin**
The target instance must have outbound internet access. This is to access repositories for drivers and dependencies like kernel-devel, gcc, patch, rpm-build, wget, dracut, make, linux-headers, and unzip. Package manager is used if needed.
An Amazon SNS topic is required to send notifications for approvals and updates. For more information about creating an Amazon SNS topic, see [Creating an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) in the *Amazon Simple Notification Service Developer Guide*.
This runbook supports the following operating systems:
+ RHEL 7.x - 8.5
+ Amazon Linux (2018.03), Amazon Linux 2
+ Debian Server
+ Ubuntu Server 18.04 LTS, 20.04 LTS, and 20.10 STR
+ SUSE Linux Enterprise Server (SUSE12SP5, SUSE15SP2)
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-MigrateXenToNitroLinux)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
+ Acknowledgement
Type: String
Description: (Required) Read the complete details of the actions performed by this automation runbook, and enter **Yes, I understand and acknowledge** to proceed with using the runbook.
+ ApproverIAM
Type: String
Description: (Required) The ARNs of IAM roles, users, or user names who can provide approvals to the automation. You can specify a maximum of 10 approvers.
+ DeleteResourcesOnFailure
Type: Boolean
Description: (Optional) Determines whether the newly created instance and AMI for the migration are deleted if the automation fails.
Valid values: True \$1 False
Default: True
+ MinimumRequiredApprovals
Type: String
Description: (Optional) The minimum number of approvals required to continue running the automation when approvals are requested.
Valid values: 1-10
Default: 1
+ NitroInstanceType
Type: String
Description: (Required) The Nitro instance type that you want to change the instance to. Supported instance types include M5, M6, C5, C6, R5, R6, and T3.
Default: m5.xlarge
+ OperationType
Type: String
Description: (Required) The operation that you want to perform. The `FullMigration` option performs the same tasks as `Clone&Migrate` and additionally replaces the root volume of your target instance. The root volume of the target instance is replaced with the root volume from the newly created instance following the migration process. The `FullMigration` operation does not support root volumes defined by Logical Volume Manager (LVM).
Valid values: Clone&Migrate \$1 FullMigration
+ SNSTopicArn
Type: String
Description: (Required) The ARN of the Amazon SNS topic for approval notification. The Amazon SNS topic is used to send required approval notifications during the automation.
+ TargetInstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instances to migrate.
## Clone&Migrate workflow
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:DescribeAutomationExecutions`
+ `ssm:StartAutomationExecution`
+ `ssm:DescribeInstanceInformation`
+ `ssm:DescribeAutomationStepExecutions`
+ `ssm:SendCommand`
+ `ssm:GetAutomationExecution`
+ `ssm:ListCommands`
+ `ssm:ListCommandInvocations`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceTypeOfferings`
+ `ec2:DescribeInstanceTypes`
+ `ec2:DescribeImages`
+ `ec2:CreateImage`
+ `ec2:RunInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DeregisterImage`
+ `ec2:DeleteSnapshot`
+ `ec2:TerminateInstances`
+ `ec2:StartInstances`
+ `ec2:DescribeKeyPairs`
+ `ec2:StopInstances`
+ `kms:CreateGrant*`
+ `kms:ReEncrypt`
+ `ec2:ModifyInstanceAttribute`
+ `autoscaling:DescribeAutoScalingInstances`
+ `iam:passRole`
+ `iam:ListRoles`
**Document Steps**
+ `startOfPreliminaryChecksBranch` - Branches to the Preliminary checks workflow.
+ `getTargetInstanceProperties` - Gathers details from the target instance.
+ `checkIfNitroInstanceTypeIsSupportedInAZ` - Determines if the target Amazon EC2 instance type is supported in the same Availability Zone as the target instance.
+ `getXenInstanceTypeDetails` - Gathers details about the source instance type.
+ `checkIfInstanceHypervisorIsNitroAlready` - Checks if the target instance is already running as a Nitro instance type.
+ `checkIfTargetInstanceLifecycleIsSpot` - Checks if the purchasing option of the target instance is Spot.
+ `checkIfOperatingSystemIsLinux` - Checks if the target instance OS is Linux.
+ `verifySSMConnectivityForTargetInstance` - Verifies that the target instance is managed by Systems Manager.
+ `checkIfEphemeralVolumeAreSupported` - Checks if the current instance type of the target instance supports instance store volumes.
+ `verifyIfTargetInstanceHasEphemeralVolumesAttached` - Checks if the target instance has instance store volumes attached.
+ `checkIfRootVolumeIsEBS` - Checks if the target instance's root volume type is EBS.
+ `checkIfTargetInstanceIsInASG` - Checks if the target instance is a part of an Auto Scaling group.
+ `endOfPreliminaryChecksBranch` - End of the Preliminary checks branch.
+ `startOfTestBranch` - Branches to the Testing workflow.
+ `createTestImage` - Creates a test AMI of the target instance.
+ `launchTestInstanceInSameSubnet` - Launches a test instance from the test AMI using the same configuration as target instance.
+ `cleanupTestInstance` - Terminates the test instance.
+ `endOfTestBranch` - End of the Testing branch.
+ `checkIfTestingBranchSucceeded` - Checks the status of the Testing branch.
+ `approvalToStopTargetInstance` - Waits for approval from the designated principals to stop the target instance.
+ `stopTargetEC2Instance` - Stops the target instance.
+ `forceStopTargetEC2Instance` - Force stops the target instance only if the previous step fails to stop the instance.
+ `startOfCloneAndMigrateBranch` - Branches to the Clone&Migrate workflow.
+ `createBackupImage` - Creates an AMI of the target instance to serve as a backup.
+ `launchInstanceInSameSubnet` - Launches a new instance from the backup AMI using the same configuration as the source instance.
+ `waitForClonedInstanceToPassStatusChecks` - Waits for the newly created instance to pass all status checks.
+ `verifySSMConnectivityForClonedInstance` - Verifies that the newly created instance is managed by Systems Manager.
+ `checkAndInstallENADrivers` - Checks if ENA drivers are installed on the newly created instance, and installs the drivers if needed.
+ `checkAndAddNVMEDrivers` - Checks if NVMe drivers are installed on the newly created instance, and installs the drivers if needed.
+ `checkAndModifyFSTABEntries` - Checks if device names are used in `/etc/fstab` and replaces them with UUIDs if needed.
+ `stopClonedInstance` - Stops the newly created instance.
+ `forceStopClonedInstance` - Force stops the newly created instance only if the previous step fails to stop the instance.
+ `checkENAAttributeForClonedInstance` - Checks if the enhanced networking attribute is turned on for the newly created instance.
+ `setNitroInstanceTypeForClonedInstance` - Changes the instance type for the newly created instance to the Nitro instance type that you specify.
+ `startClonedInstance` - Starts the newly created instance whose instance type you changed.
+ `approvalForCreatingImageAfterDriversInstallation` - If the instance successfully starts as a Nitro instance type, the automation waits for approval from the required principals. If approval is provided, an AMI is created to be used as a Golden AMI.
+ `createImageAfterDriversInstallation` - Creates an AMI to be used as a Golden AMI.
+ `endOfCloneAndMigrateBranch` - End of Clone&Migrate branch.
+ `cleanupTestImage` - Deregisters the AMI created for testing.
+ `failureHandling` - Checks if you chose to terminate resources on failure.
+ `onFailureTerminateClonedInstance` - Terminates the newly created instance if the automation fails.
+ `onFailurecleanupTestImage` - Deregisters the AMI created for testing.
+ `onFailureApprovalToStartTargetInstance` - If the automation fails, waits for approval from the designated principals to start the target instance.
+ `onFailureStartTargetInstance` - If the automation fails, starts the target instance.
## FullMigration workflow
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:DescribeAutomationExecutions`
+ `ssm:DescribeInstanceInformation`
+ `ssm:DescribeAutomationStepExecutions`
+ `ssm:SendCommand`
+ `ssm:GetAutomationExecution`
+ `ssm:ListCommands`
+ `ssm:ListCommandInvocations`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceTypeOfferings`
+ `ec2:DescribeInstanceTypes`
+ `ec2:DescribeImages`
+ `ec2:CreateImage`
+ `ec2:RunInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DeregisterImage`
+ `ec2:DeleteSnapshot`
+ `ec2:TerminateInstances`
+ `ec2:StartInstances`
+ `ec2:DescribeKeyPairs`
+ `ec2:StopInstances`
+ `kms:CreateGrant*`
+ `kms:ReEncrypt`
+ `ec2:ModifyInstanceAttribute`
+ `ec2:DetachVolume`
+ `ec2:AttachVolume`
+ `ec2:DescribeVolumes`
+ `autoscaling:DescribeAutoScalingInstances`
+ `iam:PassRole`
+ `ec2:CreateTags`
+ `cloudformation:DescribeStackResources`
**Document Steps**
The `FullMigration` workflow runs the same steps as the `Clone&Migrate` workflow and additionally performs the following steps:
+ `checkConcurrency` - Verifies that there is only one automation of this runbook targeting the Amazon EC2 instance that you specify. If the runbook finds another automation in progress targeting the same instance, the automation ends.
+ `getTargetInstanceProperties` - Gathers details from the target instance.
+ `checkRootVolumeTags` - Determines if the root volume of the target Amazon EC2 instance contains any AWS reserved tags.
+ `cloneTargetInstanceAndMigrateToNitro` - Starts a child automation using the `AWS-CloneXenInstanceToNitro` runbook.
+ `branchOnTheOperationType` - Branches on the value that you specify for the `OperationType` parameter.
+ `getClonedInstanceId` - Retrieves the ID of the newly launched instance from the child automation.
+ `checkIfRootVolumeIsBasedOnLVM` - Determines if the root partition is managed by LVM.
+ `branchOnTheRootVolumeLVMStatus` - If the minimum required approvals are received from the principals, the automation proceeds with the root volume replacement.
+ `manualInstructionsInCaseOfLVM` - If the root volume is managed by LVM, the automation sends output containing instructions for how to manually replace the root volumes.
+ `startOfReplaceRootEBSVolumeBranch` - Starts the Replace Root EBS Volume branch workflow.
+ `checkIfTargetInstanceIsManagedByCFN` - Determines if the target instance is managed by an AWS CloudFormation stack.
+ `branchOnCFNStackStatus` - Branches based on the status of the CloudFormation stack.
+ `approvalForRootVolumesReplacement(WithCFN)` - If the target instance was launched by CloudFormation, the automation waits for approval after the newly launched instance successfully starts as a Nitro instance type. When approvals are provided, the Amazon EBS volumes of the target instance are replaced with the root volumes from the newly launched instance.
+ `approvalForRootVolumesReplacement` - Waits for approval after the newly launched instance successfully starts as a Nitro instance type. When approvals are provided, the Amazon EBS volumes of the target instance are replaced with the root volumes from the newly launched instance.
+ `assertIfTargetEC2InstanceIsStillStopped` - Verifies that the target instance is in a `stopped` state before replacing the root volume.
+ `stopTargetInstanceForRootVolumeReplacement` - If the target instance is running, the automation stops the instance before replacing the root volume.
+ `forceStopTargetInstanceForRootVolumeReplacement` - Force stops the target instance if the previous step fails.
+ `stopClonedInstanceForRootVolumeReplacement` - Stops the newly created instance before replacing the Amazon EBS volumes.
+ `forceStopClonedInstanceForRootVolumeReplacement` - Force stops the newly created instance if the previous step fails.
+ `getBlockDeviceMappings` - Retrieves the block device mappings for both the target and newly created instances.
+ `replaceRootEbsVolumes` - Replaces the root volume of the target instance with the root volume of the newly created instance.
+ `EndOfReplaceRootEBSVolumeBranch` - End of Replace Root EBS Volume branch workflow.
+ `checkENAAttributeForTargetInstance` - Checks if the enhanced networking (ENA) attribute is turned on for the target Amazon EC2 instance.
+ `enableENAAttributeForTargetInstance` - Turns on the ENA attribute for the target Amazon EC2 instance if needed.
+ `setNitroInstanceTypeForTargetInstance` - Changes the target instance to the Nitro instance type that you specify.
+ `replicateRootVolumeTags` - Replicates the tags on the root Amazon EBS volume from the target Amazon EC2 instance.
+ `startTargetInstance` - Starts the target Amazon EC2 instance after changing the instance type.
+ `onFailureStopTargetEC2Instance` - Stops the target Amazon EC2 instance if it fails to start as a Nitro instance type.
+ `onFailureForceStopTargetEC2Instance` - Force stops the target Amazon EC2 instance if the previous step fails.
+ `OnFailureRevertOriginalInstanceType` - Reverts the target Amazon EC2 instance to the original instance type if the target instance fails to start as a Nitro instance type.
+ `onFailureRollbackRootVolumeReplacement` - Reverts all the changes made by the `replaceRootEbsVolumes` step if needed.
+ `onFailureApprovalToStartTargetInstance` - Waits for designated principal's approval to start the target Amazon EC2 instance after rolling back the previous changes.
+ `onFailureStartTargetInstance` - Starts the target Amazon EC2 instance.
+ `terminateClonedEC2Instance` - Terminates the cloned Amazon EC2 instance after replacing the root Amazon EBS volume.
# `AWSSupport-ResetAccess`
**Description**
This runbook will use the EC2Rescue tool on the specified EC2 instance to re-enable password decryption using the EC2 Console (Windows) or to generate and add a new SSH key pair (Linux). If you lost your key pair, this automation will create a password-enabled AMI that you can use to launch a new EC2 instance with a key pair you own (Windows).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ResetAccess)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ EC2RescueInstanceType
Type: String
Valid values: t2.small \$1 t2.medium \$1 t2.large
Default: t2.small
Description: (Required) The EC2 instance type for the EC2Rescue instance. Recommended size: t2.small.
+ InstanceId
Type: String
Description: (Required) ID of the EC2 instance you want to reset access for.
**Important**
Systems Manager Automation stops this instance, and creates an AMI before attempting any operations. Data stored in instance store volumes will be lost. The public IP address will change if you are not using an Elastic IP.
+ SubnetId
Type: String
Default: CreateNewVPC
Description: (Optional) The subnet ID for the EC2Rescue instance. By default, Systems Manager Automation creates a new VPC. Alternatively, Use SelectedInstanceSubnet to use the same subnet as your instance, or specify a custom subnet ID.
**Important**
The subnet must be in the same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
You must have at least **ssm:StartAutomationExecution**, **ssm:GetParameter** (to retrieve the SSH key parameter name) and **ssm:GetAutomationExecution** to be able to read the automation output. For more information about the required permissions, see [`AWSSupport-StartEC2RescueWorkflow`](automation-awssupport-startec2rescueworkflow.md).
**Document Steps**
1. `aws:assertAwsResourceProperty` - Assert if the provided instance is Windows.
1. (EC2Rescue for Windows) If the provided instance is Windows:
1. `aws:executeAutomation` - Invoke `AWSSupport-StartEC2RescueWorkflow` with the EC2Rescue for Windows offline password reset script
1. `aws:executeAwsApi` - Retrieve the backup AMI ID from the nested automation
1. `aws:executeAwsApi` - Retrieve the password-enabled AMI ID from the nested automation
1. `aws:executeAwsApi` - Retrieve the EC2Rescue summary from the nested automation
1. (EC2Rescue for Linux) If the provided instance is Linux:
1. `aws:executeAutomation` - Invoke `AWSSupport-StartEC2RescueWorkflow` with the EC2Rescue for Linux offline SSH key injection script
1. `aws:executeAwsApi` - Retrieve the backup AMI ID from the nested automation
1. `aws:executeAwsApi` - Retrieve the SSM parameter name for the injected SSH key
1. `aws:executeAwsApi` - Retrieve the EC2Rescue summary from the nested automation
**Outputs**
getEC2RescueForWindowsResult.Output
getWindowsBackupAmi.ImageId
getWindowsPasswordEnabledAmi.ImageId
getEC2RescueForLinuxResult.Output
getLinuxBackupAmi.ImageId
getLinuxSSHKeyParameter.Name
# `AWSSupport-ResetLinuxUserPassword`
**Description**
The `AWSSupport-ResetLinuxUserPassword` runbook helps you reset the password of a local operating system (OS) user. This runbook is especially helpful for users who need to access their Amazon Elastic Compute Cloud (Amazon EC2) instances using the serial console. The runbook creates a temporary Amazon EC2 instance in your AWS account with either an automatically generated AWS Identity and Access Management (IAM) role or a custom IAM instance profile you specify. The custom (IAM) instance profile must have permissions to retrieve the AWS Secrets Manager secret value containing the password.
The runbook stops your target Amazon EC2 instance, detaches the root Amazon Elastic Block Store (Amazon EBS) volume, and attaches it to the temporary Amazon EC2 instance. Using Run Command, a script runs on the temporary instance to set the password of the OS user that you specify. Then, the root Amazon EBS volume is reattached to your target instance. The runbook also provides an option to create a snapshot of the root volume at the beginning of the automation.
**Before you begin**
Create an Secrets Manager secret with the value of the password that you want to assign to your OS user. The value must be in plaintext. For more information, see [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) in the *AWS Secrets Manager User Guide*.
**Considerations**
+ We recommend backing up your instance before using this runbook. Consider setting the value of the `CreateSnapshot` parameter as **Yes**.
+ Changing the local user password requires the runbook to stop your instance. When an instance is stopped, any data stored in memory or on instance store volumes is lost. Also, any automatically assigned public IPv4 addresses are released. For more information about what happens when you stop an instance, see [Stop and start your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html) in the *Amazon EC2 User Guide*.
+ If the Amazon EBS volumes attached to your target Amazon EC2 instance are encrypted with a customer managed AWS Key Management Service (AWS KMS) key, make sure the AWS KMS key is not `deleted` or `disabled` or your instance will fail to start.
+ Using a custom IAM instance profile requires the `AutomationAssumeRole` to have IAM `GetInstanceProfile` permission for validation, and the custom instance profile itself must include Systems Manager and Secrets Manager access permissions. The runbook validates instance profile existence upfront but will fail during helper instance operations if the instance profile lacks required access.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ResetLinuxUserPassword)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 Linux instance that contains the OS user password that you want to reset.
+ LinuxUserName
Type: String
Default: ec2-user
Description: (Optional) The OS user account whose password you want to reset.
+ SecretArn
Type: String
Description: (Required) The ARN of your Secrets Manager secret containing the new password.
+ SecurityGroupId
Type: String
Description: (Optional) The ID of the security group to attach to the temporary Amazon EC2 instance. If you don't provide a value for this parameter, the default Amazon Virtual Private Cloud (Amazon VPC) security group is used.
+ SubnetId
Type: String
Description: (Optional) The ID of the subnet that you want to launch the Amazon EC2 temporary instance in to. By default, the automation chooses the same subnet as your target instance. If you choose to provide a different subnet, it must be in the same Availability Zone as the target instance and have access to Systems Manager endpoints.
+ CreateSnapshot
Type: String
Valid values: Yes \$1 No
Default: Yes
Description: (Optional) Determines whether a snapshot of the root volume of your target Amazon EC2 instance is created before the automation runs.
+ StopConsent
Type: String
Valid values: Yes \$1 No
Default: No
Description: Enter **Yes** to acknowledge that your target Amazon EC2 instance will be stopped during this automation. When the Amazon EC2 instance is stopped, any data stored in memory or instance store volumes is lost, and the automatic public IPv4 address is released. For more information, see [Stop and start your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html) in the *Amazon EC2 User Guide*.
+ InstanceProfileName
Type: String
Description: (Optional) The name of the IAM instance profile to attach to the helper Amazon EC2 instance. If not provided, a temporary instance profile with the required permissions will be created automatically. The custom instance profile must have permissions to access the specified Secrets Manager secret and Systems Manager.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:DescribeInstanceInformation`
+ `ssm:ListTagsForResource`
+ `ssm:SendCommand`
+ `ec2:AttachVolume`
+ `ec2:CreateSnapshot`
+ `ec2:CreateSnapshots`
+ `ec2:CreateVolume`
+ `ec2:DescribeImages`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DescribeSnapshotAttribute`
+ `ec2:DescribeSnapshots`
+ `ec2:DescribeSnapshotTierStatus`
+ `ec2:DescribeVolumes`
+ `ec2:DescribeVolumeStatus`
+ `ec2:DetachVolume`
+ `ec2:RunInstances`
+ `ec2:StartInstances`
+ `ec2:StopInstances`
+ `ec2:TerminateInstances`
+ `cloudformation:CreateStack`
+ `cloudformation:DeleteStack`
+ `cloudformation:DescribeStackResource`
+ `cloudformation:DescribeStacks`
+ `cloudformation:ListStacks`
+ `logs:CreateLogDelivery`
+ `logs:CreateLogGroup`
+ `logs:DeleteLogDelivery`
+ `logs:DeleteLogGroup`
+ `logs:DescribeLogGroups`
+ `logs:DescribeLogStreams`
+ `logs:PutLogEvents`
+ `iam:GetInstanceProfile`
**Document Steps**
1. `aws:branch` – Branches based on whether you have provided consent to stopping the target Amazon EC2 instance.
1. `aws:assertAwsResourceProperty` – Ensures the Amazon EC2 instance status is in a `running` or `stopped` state. Otherwise, the automation ends.
1. `aws:executeAwsApi` – Gets the Amazon EC2 instance properties.
1. `aws:executeAwsApi` – Gets the root volume properties.
1. `aws:branch` – Branches the automation depending on whether a subnet ID for the temporary Amazon EC2 instance was provided.
1. `aws:assertAwsResourceProperty` – Ensures the subnet that you specify in `SubnetId` parameter is in the same Availability Zone as the target Amazon EC2 instance.
1. `aws:assertAwsResourceProperty`– Ensures the target Amazon EC2 instance root volume is an Amazon EBS volume.
1. `aws:assertAwsResourceProperty` – Ensures the Amazon EC2 instance architecture is `arm64` or `x86_64`.
1. `aws:assertAwsResourceProperty` – Ensures the Amazon EC2 instance shutdown behavior is `stop` and not `terminate`.
1. `aws:branch` – Ensures the Amazon EC2 instance is not a Spot Instance. Otherwise, the automation ends.
1. `aws:executeScript` – Ensures the Amazon EC2 instance is not part of an auto scaling group. If the instance is part of an auto scaling group, the automation confirms the Amazon EC2 instance is in a `Standby` lifecycle state.
1. `aws:branch` – Branches the automation depending on whether a custom IAM instance profile name was provided or not
1. `aws:assertAwsResourceProperty` – Ensures the custom IAM instance profile exists and validates its name matches the input parameter.
1. `aws:createStack` – Creates a temporary Amazon EC2 instance that is used to reset the password for the OS user that you specify.
1. `aws:waitForAwsResourceProperty` – Waits until the newly launched temporary Amazon EC2 instance is running.
1. `aws:executeAwsApi` – Gets the ID of the temporary Amazon EC2 instance.
1. `aws:waitForAwsResourceProperty` – Waits for the temporary Amazon EC2 instance to report as managed by Systems Manager.
1. `aws:changeInstanceState`– Stops the target Amazon EC2 instance.
1. `aws:changeInstanceState` – Forces the target Amazon EC2 instance to stop in case it gets stuck in a stopping state.
1. `aws:branch` – Branches the automation depending on whether a snapshot of the root volume of the target Amazon EC2 instance was requested.
1. `aws:executeAwsApi` – Creates a snapshot of the target Amazon EC2 instance root Amazon EBS volume.
1. `aws:waitForAwsResourceProperty` – Waits for the snapshot to be in a `completed` state.
1. `aws:executeAwsApi` – Detaches the Amazon EBS root volume from the target Amazon EC2 instance.
1. `aws:waitForAwsResourceProperty` – Waits for the Amazon EBS root volume to be detached from the target Amazon EC2 instance.
1. `aws:executeAwsApi` – Attaches the root Amazon EBS volume to the temporary Amazon EC2 instance.
1. `aws:waitForAwsResourceProperty` – Waits for the Amazon EBS root volume to be attached to the temporary Amazon EC2 instance.
1. `aws:runCommand` – Resets the target user password by running a shell script using Run Command on the temporary Amazon EC2 instance.
1. `aws:executeAwsApi` – Detaches the Amazon EBS root volume from the temporary Amazon EC2 instance.
1. `aws:waitForAwsResourceProperty` – Waits for the Amazon EBS root volume to be detached from the temporary Amazon EC2 instance.
1. `aws:executeAwsApi` – Detaches the Amazon EBS root volume from the temporary Amazon EC2 instance after an error.
1. `aws:waitForAwsResourceProperty` – Waits for the Amazon EBS root volume to be detached from the temporary Amazon EC2 instance after an error.
1. `aws:branch` – Branches the automation depending on whether a snapshot of the root volume was requested to determine the recovery path in case of an error.
1. `aws:executeAwsApi` – Reattaches the root Amazon EBS volume to the target Amazon EC2 instance.
1. `aws:waitForAwsResourceProperty` – Waits for the Amazon EBS root volume to be attached to the Amazon EC2 instance.
1. `aws:executeAwsApi` – Creates a new Amazon EBS volume from the target Amazon EC2 instance root volume snapshot.
1. `aws:waitForAwsResourceProperty` – Waits until the new Amazon EBS volume is in an `available` state.
1. `aws:executeAwsApi` – Attaches the new Amazon EBS volume to the target instance as the root volume.
1. `aws:waitForAwsResourceProperty` – Waits for the Amazon EBS volume to be in an `attached` state.
1. `aws:executeAwsApi` – Describes the CloudFormation stack events if the runbooks fails to create or update the CloudFormation stack.
1. `aws:branch` – Branches the automation depending on the previous Amazon EC2 instance state. If the state was `running`, the instance is started. If it was in a `stopped` state, the automation continues.
1. `aws:changeInstanceState` – Starts the Amazon EC2 instance if needed.
1. `aws:waitForAwsResourceProperty` – Waits until the CloudFormation stack is in a terminal status before deleting.
1. `aws:executeAwsApi` – Deletes the CloudFormation stack including the temporary Amazon EC2 instance.
# `AWSSupport-RunEC2RescueForWindowsTool`
**Description**
The **AWSSupport-RunEC2RescueForWindowsTool** runbook runs the Amazon EC2 Rescue for Windows Server troubleshooting tool on the target Amazon Elastic Compute Cloud (Amazon EC2) Windows managed instance to help troubleshoot common issues. This runbook supports three main actions:
+ **ResetAccess**: Resets the local Administrator password. The password is randomly generated and securely stored in AWS Systems Manager Parameter Store as `/EC2Rescue/Password/`. If you provide no parameters, the password is encrypted with the default AWS Key Management Service (AWS KMS) key `alias/aws/ssm`. Optionally, you can specify a AWS KMS key ID to encrypt the password with your own key.
+ **CollectLogs**: Collects logs and configuration files from the operating system and uploads them to an Amazon Simple Storage Service (Amazon S3) bucket in your account by running Amazon EC2 Rescue with the `/collect:all` option.
+ **FixAll**: Attempts to detect and address issues on an offline Windows root volume attached to the current instance by running Amazon EC2 Rescue with the `/rescue:all` option.
**Important**
This runbook requires that the target instance is a Windows managed instance with the AWS Tools for Windows PowerShell installed. The runbook installs the Amazon EC2 Rescue for Windows Server tool using the Systems Manager Distributor package `AWSSupport-EC2Rescue`.
**How does it work?**
The runbook performs the following steps:
+ Installs the Amazon EC2 Rescue for Windows Server troubleshooting tool using the Systems Manager Distributor package.
+ Executes the specified action (`ResetAccess`, `CollectLogs`, or `FixAll`) with the provided parameters.
+ For `ResetAccess`: Generates a secure password and stores it in Parameter Store.
+ For `CollectLogs`: Collects system logs and uploads them to the specified Amazon S3 bucket.
+ For `FixAll`: Attempts to fix issues on the specified offline volume.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-RunEC2RescueForWindowsTool)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:SendCommand`
+ `ssm:ListCommandInvocations`
+ `ssm:DescribeInstanceInformation`
+ `ssm:GetCommandInvocation`
+ `ssm:PutParameter` (for ResetAccess action)
+ `kms:Encrypt` (for ResetAccess action with custom AWS KMS key)
+ `s3:PutObject` (for CollectLogs action)
+ `s3:GetBucketAcl` (for CollectLogs action)
+ `s3:GetBucketPolicy` (for CollectLogs action)
+ `s3:GetBucketPolicyStatus` (for CollectLogs action)
Example Policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:ListCommandInvocations",
"ssm:DescribeInstanceInformation",
"ssm:GetCommandInvocation",
"ssm:PutParameter",
"kms:Encrypt",
"s3:PutObject",
"s3:GetBucketAcl",
"s3:GetBucketPolicy",
"s3:GetBucketPolicyStatus"
],
"Resource": "*"
}
]
}
```
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-RunEC2RescueForWindowsTool/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-RunEC2RescueForWindowsTool/description) in Systems Manager under Documents.
1. Select **Execute automation.**
1. For the input parameters, enter the following:
+ **Command (Required):**
+ Description: (Required) The action to perform.
+ Type: `String`
+ Allow Values: `[ResetAccess, CollectLogs, FixAll]`
+ Default: `ResetAccess`
+ **Parameters (Required):**
+ Description: (Required) Parameters for the command:
+ For `ResetAccess`: The AWS AWS KMS key ID or alias (default: `alias/aws/ssm`)
+ For `CollectLogs`: The Amazon S3 bucket name to upload the logs to
+ For `FixAll`: The device name for the offline remediation (for example, `xvdf`)
+ Type: `String`
+ Allow Pattern: `^[0-9a-z][a-z0-9-.]{3,63}$|^(dev\/[a-z0-9]{2,10}|xv[a-z0-9]{1,10})$|^(alias\\aws\\ssm|[a-zA-Z0-9-/_]{1,32})$`
1. Select **Execute**.
1. The automation initiates.
1. The document performs the following steps:
+ **installEC2Rescue**:
Installs the Amazon EC2 Rescue for Windows Server troubleshooting tool using the Systems Manager Distributor package `AWSSupport-EC2Rescue`.
+ **runEC2RescueForWindows**:
Runs the PowerShell script with the action specified in the Command parameter to perform the requested operation.
1. After completion, review the **Outputs** section for the detailed results of the execution.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-RunEC2RescueForWindowsTool/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
+ [Use Amazon EC2 Rescue for Windows Server with Systems Manager Run Command](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/ec2rw-ssm.html)
# `AWSPremiumSupport-ResizeNitroInstance`
**Description**
The `AWSPremiumSupport-ResizeNitroInstance` runbook provides an automated solution for resizing Amazon Elastic Compute Cloud (Amazon EC2) instances built on the Nitro System.
To reduce the potential risk of data loss and downtime, the runbook verifies the following:
+ Instance stop behavior.
+ If the instance is part of an Amazon EC2 Auto Scaling group, and in `standby` mode.
+ Instance state and tenancy.
+ The instance type you want to change to supports the number of network interfaces currently attached to your instance.
+ The processor architecture and virtualization type for both the current and target instance type are the same.
+ If the instance is running, that it's passing all status checks.
+ The instance type you want to change to is available in the same Availability Zone.
If the Amazon EC2 does not pass status checks after changing the instance type, the runbook automatically rolls back to the previous instance type.
By default, this runbook will not change the instance type if it is running and instance store volumes are attached. The runbook will also not change the instance type if the instance is part of an AWS CloudFormation stack. If you want to change either of these behaviors, specify `yes` for the `AllowInstanceStoreInstances` and `AllowCloudFormationInstances` parameters.
The runbook provides two different ways to specify the instance type you want to change to:
+ For simple automations targeting a single instance, specify the instance type you want to change to using the `TargetInstanceTypeFromParameter` parameter.
+ For running automations at scale to change the instance type of several instances, specify the instance type using the `TargetInstanceTypeFromTagValue` parameter. For information about running automations at scale, see [Run automations at scale](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-working-targets-and-rate-controls.html).
If you don't specify a value for either parameter, the automation fails.
**Important**
Access to `AWSPremiumSupport-*` runbooks requires a Business \$1 Support, Enterprise Support or Unified Operations Subscription. For more information, see [Compare AWS Support Plans](https://aws.amazon.com/premiumsupport/plans/).
**Considerations**
+ We recommend backing up your instance before using this runbook.
+ For information about compatibility for changing instance types, see [Compatibility for changing the instance type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/resize-limitations.html).
+ If the automation fails and rolls back to the original instance type, see [Troubleshoot changing the instance type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/troubleshoot-change-instance-type.html).
+ Changing the instance type requires the runbook to stop your instance. When an instance is stopped, any data stored in memory or on instance store volumes is lost. Also, any automatically assigned public IPv4 addresses are released. For more information about what happens when you stop an instance, see [Stop and start your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html).
+ By using the `SkipInstancesWithTagKey` parameter, you can skip instances that have a specific Amazon EC2 tag key applied.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSPremiumSupport-ResizeNitroInstance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, Windows
**Parameters**
+ 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.
+ Acknowledge
Type: String
Description: (Required) Enter **yes** to acknowledge that your instance will be stopped if it's currently running.
+ AllowInstanceStoreInstances
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If you specify `yes`, you allow the runbook to run on instances that have instance store volumes attached.
+ AllowCloudFormationInstances
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If you specify `yes`, the runbook runs on instances that are part of an CloudFormation stack.
+ DryRun
Type: String
Valid values: no \$1 yes
Default: no
Description: (Optional) If you specify `yes`, the runbook validates resizing requirements without making changes to the instance type.
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instance whose type you want to change.
+ SkipInstancesWithTagKey
Type: String
Description: (Optional) The automation skips a target instance if the tag key you specify is applied to the instance.
+ SleepTime
Type: String
Default: 3
Description: (Optional) The number of seconds this runbook should sleep after completion.
+ TagInstance
Type: String
Description: (Optional) Tag the instances with the key and value of your choice using the following format: *Key=ChangingType,Value=True*. This option allows you to track instances that have been targeted by this runbook. Tag keys and values are case sensitive.
+ TargetInstanceTypeFromParameter
Type: String
Description: (Optional) The instance type you want to change your instance to. Leave this parameter empty if you want to use the value of the tag key provided in the `TargetInstanceTypeFromTagValue` parameter.
+ TargetInstanceTypeFromTagValue
Type: String
Description: (Optional) The tag key applied to your target instances whose value contains the instance type you want to change to. If you specify a value for the `TargetInstanceTypeFromParameter` parameter, it overrides any value you specify for this parameter.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `autoscaling:DescribeAutoScalingInstances`
+ `cloudformation:DescribeStackResources`
+ `ssm:GetAutomationExecution`
+ `ssm:DescribeAutomationExecutions`
+ `ec2:DescribeInstanceAttribute`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DescribeInstanceTypeOfferings`
+ `ec2:DescribeInstanceTypes`
+ `ec2:DescribeTags`
+ `ec2:ModifyInstanceAttribute`
+ `ec2:StartInstances`
+ `ec2:StopInstances`
**Document Steps**
1. `aws:assertAwsResourceProperty`: Ensures the Amazon EC2 instance is not tagged with the resource tag key specified in the `SkipInstancesWithTagKey` parameter. If the tag key is found applied to the instance, the step fails and the automation ends.
1. `aws:assertAwsResourceProperty`: Confirms the status of the target Amazon EC2 instance is `running`, `pending`, `stopped`, or `stopping`. Otherwise, the automation ends.
1. `aws:executeAwsApi`: Gathers properties from the Amazon EC2 instance.
1. `aws:executeAwsApi`: Gathers details about the current Amazon EC2 instance type.
1. `aws:branch`: Checks if the current instance type and the instance type specified in the `TargetInstanceTypeFromParameter` parameter are the same. If they are, the automation ends.
1. `aws:assertAwsResourceProperty`: Ensures the instance is running on the Nitro System.
1. `aws:branch`: Ensures the Amazon EC2 instance root volume type is an Amazon Elastic Block Store (Amazon EBS) volume.
1. `aws:assertAwsResourceProperty`: Confirms the instance shutdown behavior is `stop` and not `terminate`.
1. `aws:branch`: Ensures the Amazon EC2 instance is not a Spot instance.
1. `aws:branch`: Ensures the Amazon EC2 instance tenancy is default and not dedicated host, or dedicated instance.
1. `aws:executeScript`: Confirms there is only one automation of this runbook targeting the current instance ID. If another automation is already in progress targeting the same instance, the automation returns an error and ends.
1. `aws:branch`: Branches the automation based on the state of the Amazon EC2 instance.
1. If `stopped` or `stopping`, the automation runs `aws:waitForAwsResourceProperty` until the Amazon EC2 instance is fully stopped.
1. If `running` or `pending`, the automation runs `aws:waitForAwsResourceProperty` until the Amazon EC2 instance passes status checks.
1. `aws:assertAwsResourceProperty`: Confirms that the Amazon EC2 instance is not part of an Auto Scaling group by calling the `DescribeAutoScalingInstances` API operation. If the instance is part of an Auto Scaling group, ensures the Amazon EC2 instance is in `standby` mode.
1. `aws:branch`: Branches the automation depending on whether you want the automation to check if the Amazon EC2 instance is part of an CloudFormation stack:
1. `aws:executeScript` Ensures the Amazon EC2 instance is not part of an CloudFormation stack by calling the `DescribeStackResources` API operation.
1. `aws:executeAwsApi`: Returns a list of instance types with the same processor architecture type, virtulization type, and that supports the number of network interfaces currently attached to the target instance.
1. `aws:executeAwsApi`: Gets the target instance type value from the tag key specified in the `TargetInstanceTypeFromTagValue` parameter.
1. `aws:executeScript`: Confirms that the current and target instances types are compatible. Ensures that the target instance type is available in the same subnet. Verifies the principal who started the runbook has permissions to change the instance type, and stop and start the instance if it was running.
1. `aws:branch`: Branches the automation based on whether the `DryRun` parameter value is set to `yes`. If `yes`, the automation ends.
1. `aws:branch`: Checks if the original and the target instance type are the same. If they're the same, the automation ends.
1. `aws:executeAwsApi`: Gets the current instance state.
1. `aws:changeInstanceState`: Stops the Amazon EC2 instance.
1. `aws:changeInstanceState`: Forces the instance to stop if it's stuck in the `stopping` state.
1. `aws:executeAwsApi`: Changes the instance type to the target instance type.
1. `aws:sleep`: Waits 3 seconds after changing the instance type for eventual consistency.
1. `aws:branch`: Branches the automation based on the previous instance state. If it was `running`, the instance is started.
1. `aws:changeInstanceState`: Starts the Amazon EC2 instance if it was running before changing the instance type.
1. `aws:waitForAwsResourceProperty`: Waits for the Amazon EC2 instance to pass status checks. If the instance doesn't pass status checks, the instance is changed back to its original instance type.
1. `aws:changeInstanceState`: Stops the Amazon EC2 instance before changing it to its original instance type.
1. `aws:changeInstanceState`: Forces the Amazon EC2 instance to stop before changing it to its original instance type in case it gets stuck in a stopping state.
1. `aws:executeAwsApi`: Changes the Amazon EC2 instance to its original type.
1. `aws:sleep`: Waits 3 seconds after changing the instance type for eventual consistency.
1. `aws:changeInstanceState`: Starts the Amazon EC2 instance if it was running before changing the instance type.
1. `aws:waitForAwsResourceProperty`: Waits for the Amazon EC2 instance to pass status checks.
1. `aws:sleep`: Waits before ending the runbook.
# `AWSSupport-ShareEncryptedAMIOrEBSSnapshot`
**Description**
This runbook automates the process of sharing encrypted Amazon Machine Images or Amazon Elastic Block Store snapshots with other Amazon Web Services accounts. This runbook handles the complex requirements for cross-account sharing of encrypted resources, including AWS Key Management Service key policy modifications and resource permission updates.
This automation performs the steps outlined in the AWS Security Blog article [How to share encrypted AMIs across accounts to launch encrypted Amazon Elastic Compute Cloud instances](https://aws.amazon.com/blogs/security/how-to-share-encrypted-amis-across-accounts-to-launch-encrypted-ec2-instances/).
**Important Considerations**
**This runbook will modify your resources**: The runbook will add cross-account permissions to your AWS KMS Customer Managed Key (CMK) policy and grant AMI launch permissions or Amazon EBS snapshot create volume permissions to the destination account.
**Additional costs may apply**: When copying resources (different region or AWS managed key encryption), additional costs will be incurred for the new AMI or Amazon EBS snapshot and any cross-region data transfer.
**Please verify the destination account ID**: Double-check the destination account ID as this runbook cannot validate account existence.
**Automatic rollback with manual verification**: This runbook attempts to automatically roll back changes if it fails. However, if the rollback itself fails, please verify that no extra AMI/Snapshot copies were left in your account, resource LaunchPermission/CreateVolumePermission attributes do not include unintended accounts, and AWS KMS key policy is in its original state.
**How does it work?**
The runbook performs the following high-level steps:
+ Validates the input resource existence, state, and encryption configuration
+ Checks current resource sharing permissions with the destination account
+ Analyzes AWS KMS key policy and creates a comprehensive preview of all required changes
+ Requests approval from designated principals before making any changes
+ Executes approved changes including resource copying (if needed), permission updates, and AWS KMS key policy modifications
+ Provides a comprehensive execution report with rollback information if needed
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-ShareEncryptedAMIOrEBSSnapshot)
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
The AutomationAssumeRole parameter requires the following actions:
+ ec2:DescribeImages
+ ec2:DescribeSnapshots
+ ec2:DescribeImageAttribute
+ ec2:DescribeSnapshotAttribute
+ ec2:ModifyImageAttribute
+ ec2:ModifySnapshotAttribute
+ ec2:CopyImage
+ ec2:CopySnapshot
+ ec2:DeregisterImage
+ ec2:DeleteSnapshot
+ kms:DescribeKey
+ kms:GetKeyPolicy
+ kms:PutKeyPolicy
+ kms:CreateGrant
+ kms:GenerateDataKey\$1
+ kms:ReEncrypt\$1
+ kms:Decrypt
+ accessanalyzer:CheckAccessNotGranted
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-ShareEncryptedAMIOrEBSSnapshot/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-ShareEncryptedAMIOrEBSSnapshot/description) in Systems Manager under Documents.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
The Amazon Resource Name of the AWS AWS Identity and Access Management 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.
+ **Approvers (Required):**
The list of AWS authenticated principals who are able to either approve or reject the action. The maximum number of approvers is 10. You can specify principals by using any of the following formats: user name, user ARN, IAM role ARN, or IAM assume role ARN.
+ **ResourceId (Required):**
AMI or Amazon EBS Snapshot ID to be shared (e.g., ami-123456789012 or snap-123456789012).
+ **DestinationAccountId (Required):**
The 12-digit AWS account ID where the resource will be shared.
+ **CustomerManagedKeyId (Optional):**
AWS KMS CMK ID to re-encrypt the resource. Required if the resource is encrypted with AWS managed key or when DestinationRegion is specified for cross-region copying. For cross-region copying, this key must exist in the destination region.
+ **DestinationRegion (Optional):**
The AWS region where the resource will be copied. The default value is the current region. If a different region is specified, the resource will be copied to the destination region using the AWS KMS CMK specified in the CustomerManagedKeyId parameter.
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **`ValidateResources`**:
Validates input resource existence, state, encryption configuration, and determines required changes for sharing.
+ **`BranchOnResourcePermission`**:
Branches the workflow based on whether resource sharing permission need to be checked.
+ **`CheckResourcePermission`**:
Checks if the target account has required sharing permission for the resource.
+ **`AnalyzeChanges`**:
Analyzes AWS KMS key policy and creates comprehensive preview of all required changes.
+ **`BranchOnChanges`**:
Branches the workflow based on whether changes require approval.
+ **`GetApproval`**:
Waits for the approval of designated AWS IAM principals to proceed with required changes.
+ **`ExecuteChanges`**:
Executes approved changes with rollback on failure.
+ **`Results`**:
Generates a comprehensive execution report summarizing all actions taken during the encrypted AMI or snapshot sharing process.
1. After completed, review the Outputs section for the detailed results of the execution.
**Required AWS AWS Identity and Access Management Policy for Destination Account**
The IAM role or user in the destination account must configure the following IAM permissions to launch encrypted Amazon EC2 instances from the shared encrypted AMI or to create volumes from the shared encrypted Amazon EBS snapshot:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:DescribeKey",
"kms:ReEncrypt*",
"kms:CreateGrant",
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:::key/"
]
}
]
}
```
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-ShareEncryptedAMIOrEBSSnapshot/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
+ [Share a AWS KMS key](https://docs.aws.amazon.com//ebs/latest/userguide/share-kms-key.html)
# `AWSSupport-RestoreEC2InstanceFromSnapshot`
**Description**
The `AWSSupport-RestoreEC2InstanceFromSnapshot` runbook helps you identify and restore an Amazon Elastic Compute Cloud (Amazon EC2) instance from a working Amazon Elastic Block Store (Amazon EBS) snapshot of the root volume.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-RestoreEC2InstanceFromSnapshot)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ EndDate
Type: String
Description: (Optional) The last date you want the automation to look for a snapshot.
+ InplaceSwap
Type: Boolean
Valid values: true \$1 false
Description: (Optional) If the value for this parameter is set to `true`, the newly created volume from the snapshot replaces the existing root volume attached to your instance.
+ InstanceId
Type: String
Description: (Required) The ID of the instance you want to restore from a snapshot.
+ LookForInstanceStatusCheck
Type: Boolean
Valid values: true \$1 false
Default: true
Description: (Optional) If the value for this parameter is set to `true`, the automation checks whether instance status checks fail on the test instances launched from the snapshots.
+ SkipSnapshotsBy
Type: String
Description: (Optional) The interval at which snapshots are skipped when searching for snapshots to restore your instance. For example, if there are 100 snapshots available, and you specify a value of 2 for this parameter, then every third snapshot is reviewed.
Default: 0
+ SnapshotId
Type: String
Description: (Optional) The ID of a snapshot you want to restore the instance from.
+ StartDate
Type: String
Description: (Optional) The first date you want the automation to look for a snapshot.
+ TotalSnapshotsToLook
Type: String
Description: (Optional) The number of snapshots the automation reviews.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:DescribeInstanceInformation`
+ `ec2:AttachVolume`
+ `ec2:CreateImage`
+ `ec2:CreateTags`
+ `ec2:CreateVolume`
+ `ec2:DeleteTags`
+ `ec2:DeregisterImage`
+ `ec2:DescribeInstances`
+ `ec2:DescribeInstanceStatus`
+ `ec2:DescribeImages`
+ `ec2:DescribeSnapshots`
+ `ec2:DescribeVolumes`
+ `ec2:DetachVolume`
+ `ec2:RunInstances`
+ `ec2:StartInstances`
+ `ec2:StopInstances`
+ `ec2:TerminateInstances`
+ `cloudwatch:GetMetricData`
**Document Steps**
1. `aws:executeAwsApi` - Gathers details about the target instance.
1. `aws:assertAwsResourceProperty` - Verifies the target instance exists.
1. `aws:assertAwsResourceProperty` - Verifies the root volume is an Amazon EBS volume.
1. `aws:assertAwsResourceProperty` - Verifies that another automation isn't already running that targets this instance.
1. `aws:executeAwsApi` - Tags the target instance.
1. `aws:executeAwsApi` - Creates an AMI of the instance.
1. `aws:executeAwsApi` - Gathers details about the AMI created in the previous step.
1. `aws:waitForAwsResourceProperty` - Waits for the AMI state to become `available` before proceeding.
1. `aws:executeScript` - Launches a new instance from the newly created AMI.
1. `aws:assertAwsResourceProperty` - Verifies the instance state is `available`.
1. `aws:executeAwsApi` - Gathers details about the newly launched instance.
1. `aws:branch` - Branches based on whether you provided a value for the `SnapshotId` parameter.
1. `aws:executeScript` - Returns a list of snapshots within the time period specified.
1. `aws:executeAwsApi` - Stops the instance.
1. `aws:waitForAwsResourceProperty` - Waits for the volume state to be `available`.
1. `aws:waitForAwsResourceProperty` - Waits for the instance state to be `stopped`.
1. `aws:executeAwsApi` - Detaches the root volume.
1. `aws:waitForAwsResourceProperty` - Waits for the root volume to be detached.
1. `aws:executeAwsApi` - Attaches the new root volume.
1. `aws:waitForAwsResourceProperty` - Waits for the new volume to be attached.
1. `aws:executeAwsApi` - Starts the instance.
1. `aws:waitForAwsResourceProperty` - Waits for the instance state to be `available`.
1. `aws:waitForAwsResourceProperty` - Waits for system and instance status checks to pass for the instance.
1. `aws:executeScript` - Runs a script to find a snapshot that can be used to successfully create a volume.
1. `aws:executeScript` - Runs a script to recover the instance using the newly created volume from the snapshot identified by the automation, or using the volume created from the snapshot you specified in the `SnapshotId` parameter.
1. `aws:executeScript` - Deletes resources created by the automation.
**Outputs**
launchCloneInstance.InstanceIds
ListSnapshotByDate.finalSnapshots
ListSnapshotByDate.remainingSnapshotToBeCheckedInSameDateRange
findWorkingSnapshot.workingSnapshot
InstanceRecovery.result
# `AWSSupport-SendLogBundleToS3Bucket`
**Description**
The `AWSSupport-SendLogBundleToS3Bucket` runbook uploads a log bundle generated by the EC2Rescue tool from the target instance to the specified S3 bucket. The runbook installs the platform specific version of EC2Rescue based on the platform of the target instance. EC2Rescue is then used to collect all the available operating system (OS) logs.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-SendLogBundleToS3Bucket)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the Windows or Linux managed instance you want to collect logs from.
+ S3BucketName
Type: String
Description: (Required) S3 bucket to upload the logs to.
+ S3Path
Type: String
Default: `AWSSupport-SendLogBundleToS3Bucket`/
Description: (Optional) S3 path for the collected logs.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
It is recommended that the EC2 instance receiving the command has an IAM role with the **AmazonSSMManagedInstanceCore** Amazon managed policy attached. The user must have at least **ssm:StartAutomationExecution** and **ssm:SendCommand** to run the automation and send the command to the instance, plus **ssm:GetAutomationExecution** to be able to read the automation output.
**Document Steps**
1. `aws:runCommand` - Install EC2Rescue via `AWS-ConfigureAWSPackage`.
1. `aws:runCommand` - Run the PowerShell script to collect Windows troubleshooting logs with EC2Rescue.
1. `aws:runCommand` - Run the bash script to collect Linux troubleshooting logs with EC2Rescue.
**Outputs**
collectAndUploadWindowsLogBundle.Output
collectAndUploadLinuxLogBundle.Output
# `AWSSupport-StartEC2RescueWorkflow`
**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.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-StartEC2RescueWorkflow)
**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]::ASCII.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 |
| --- | --- | --- |
| \$1env:EC2RESCUE\$1ACCOUNT\$1ID | \$1\$1 global:ACCOUNT\$1ID \$1\$1 | 123456789012 |
| \$1env:EC2RESCUE\$1DATE | \$1\$1 global:DATE \$1\$1 | 2018-09-07 |
| \$1env:EC2RESCUE\$1DATE\$1TIME | \$1\$1 global:DATE\$1TIME \$1\$1 | 2018-09-07\$118.09.59 |
| \$1env:EC2RESCUE\$1EC2RW\$1DIR | EC2Rescue for Windows installation path | C:\$1Program Files\$1Amazon\$1EC2Rescue |
| \$1env:EC2RESCUE\$1EC2RW\$1DIR | EC2Rescue for Windows installation path | C:\$1Program Files\$1Amazon\$1EC2Rescue |
| \$1env:EC2RESCUE\$1EXECUTION\$1ID | \$1\$1 automation:EXECUTION\$1ID \$1\$1 | 7ef8008e-219b-4aca-8bb5-65e2e898e20b |
| \$1env:EC2RESCUE\$1OFFLINE\$1CURRENT\$1CONTROL\$1SET | Offline Windows Current Control Set path | `HKLM:\AWSTempSystem\ControlSet001` |
| \$1env:EC2RESCUE\$1OFFLINE\$1DRIVE | Offline Windows drive letter | D:\$1 |
| \$1env:EC2RESCUE\$1OFFLINE\$1EBS\$1DEVICE | Offline root volume EBS device | xvdf |
| \$1env:EC2RESCUE\$1OFFLINE\$1KERNEL\$1VER | Offline Windows Kernel version | 6.1.7601.24214 |
| \$1env:EC2RESCUE\$1OFFLINE\$1OS\$1ARCHITECTURE | Offline Windows architecture | AMD64 |
| \$1env:EC2RESCUE\$1OFFLINE\$1OS\$1CAPTION | Offline Windows caption | Windows Server 2008 R2 Datacenter |
| \$1env:EC2RESCUE\$1OFFLINE\$1OS\$1TYPE | Offline Windows OS type | Server |
| \$1env:EC2RESCUE\$1OFFLINE\$1PROGRAM\$1FILES\$1DIR | Offline Windows Program files directory path | D:\$1Program Files |
| \$1env:EC2RESCUE\$1OFFLINE\$1PROGRAM\$1FILES\$1X86\$1DIR | Offline Windows Program files x86 directory path | D:\$1Program Files (x86) |
| \$1env:EC2RESCUE\$1OFFLINE\$1REGISTRY\$1DIR | Offline Windows registry directory path | D:\$1Windows\$1System32\$1config |
| \$1env:EC2RESCUE\$1OFFLINE\$1SYSTEM\$1ROOT | Offline Windows system root directory path | D:\$1Windows |
| \$1env:EC2RESCUE\$1REGION | \$1\$1 global:REGION \$1\$1 | us-west-1 |
| \$1env:EC2RESCUE\$1S3\$1BUCKET | \$1\$1 S3BucketName \$1\$1 | amzn-s3-demo-bucket |
| \$1env:EC2RESCUE\$1S3\$1PREFIX | \$1\$1 S3Prefix \$1\$1 | myprefix/ |
| \$1env:EC2RESCUE\$1SOURCE\$1INSTANCE | \$1\$1 InstanceId \$1\$1 | i-abcdefgh123456789 |
| \$1script:EC2RESCUE\$1OFFLINE\$1WINDOWS\$1INSTALL | Offline Windows Installation metadata | Customer Powershell Object |
Linux:
****
| Variable | Description | Example value |
| --- | --- | --- |
| EC2RESCUE\$1ACCOUNT\$1ID | \$1\$1 global:ACCOUNT\$1ID \$1\$1 | 123456789012 |
| EC2RESCUE\$1DATE | \$1\$1 global:DATE \$1\$1 | 2018-09-07 |
| EC2RESCUE\$1DATE\$1TIME | \$1\$1 global:DATE\$1TIME \$1\$1 | 2018-09-07\$118.09.59 |
| EC2RESCUE\$1EC2RL\$1DIR | EC2Rescue for Linux installation path | /usr/local/ec2rl-1.1.3 |
| EC2RESCUE\$1EXECUTION\$1ID | \$1\$1 automation:EXECUTION\$1ID \$1\$1 | 7ef8008e-219b-4aca-8bb5-65e2e898e20b |
| EC2RESCUE\$1OFFLINE\$1DEVICE | Offline device name | /dev/xvdf1 |
| EC2RESCUE\$1OFFLINE\$1EBS\$1DEVICE | Offline root volume EBS device | /dev/sdf |
| EC2RESCUE\$1OFFLINE\$1SYSTEM\$1ROOT | Offline root volume mount point | /mnt/mount |
| EC2RESCUE\$1PYTHON | Python version | python2.7 |
| EC2RESCUE\$1REGION | \$1\$1 global:REGION \$1\$1 | us-west-1 |
| EC2RESCUE\$1S3\$1BUCKET | \$1\$1 S3BucketName \$1\$1 | amzn-s3-demo-bucket |
| EC2RESCUE\$1S3\$1PREFIX | \$1\$1 S3Prefix \$1\$1 | myprefix/ |
| EC2RESCUE\$1SOURCE\$1INSTANCE | \$1\$1 InstanceId \$1\$1 | i-abcdefgh123456789 |
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, macOS, Windows
**Parameters**
+ 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 \$1 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 \$1 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 \$1 t2.medium \$1 t2.large \$1 t3.small \$1 t3.medium \$1 t3.large \$1 i3.large
Default: t3.medium
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
Description: (Required) Base64 encoded script to run against the helper instance. Use Bash if your source instance is Linux, and PowerShell if it is Windows.
+ 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: \$1\$1 automation:EXECUTION\$1ID \$1\$1
Description: (Optional) A unique identifier for the automation.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
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:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:111122223333:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::111122223333:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::111122223333:instance-profile/AWSSupport-EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
**Document Steps**
1. `aws:executeAwsApi` - Describe the provided instance
1. `aws:executeAwsApi` - Describe the provided instance's root volume
1. `aws:assertAwsResourceProperty` - Check the root volume device type is EBS
1. `aws:assertAwsResourceProperty` - Check the root volume is not encrypted
1. `aws:assertAwsResourceProperty` - Check the provide subnet ID
1. (Use current instance subnet) - If \$1SubnetId = SelectedInstanceSubnet\$1 then run `aws:createStack` to deploy the EC2Rescue CloudFormation stack
1. (Create new VPC) - If \$1SubnetId = CreateNewVPC\$1 then run `aws:createStack` to deploy the EC2Rescue CloudFormation stack
1. (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
1. `aws:invokeLambdaFunction` - Perform additional input validation
1. `aws:executeAwsApi` - Update the EC2Rescue CloudFormation stack to create the EC2Rescue helper instance
1. `aws:waitForAwsResourceProperty` - Wait for the EC2Rescue CloudFormation stack update to complete
1. `aws:executeAwsApi` - Describe the EC2Rescue CloudFormation stack output to obtain the EC2Rescue helper instance ID
1. `aws:waitForAwsResourceProperty` - Wait for the EC2Rescue helper instance to become a managed instance
1. `aws:changeInstanceState` - Stop the provided instance
1. `aws:changeInstanceState` - Stop the provided instance
1. `aws:changeInstanceState` - Force stop the provided instance
1. `aws:assertAwsResourceProperty` - Check the CreatePreEC2RescueBackup input value
1. (Create pre-EC2Rescue backup) - If \$1CreatePreEC2RescueBackup = true\$1
1. `aws:executeAwsApi` - Create an AMI backup of the provided instance
1. `aws:createTags` - Tag the AMI backup
1. `aws:runCommand` - Install EC2Rescue on the EC2Rescue helper instance
1. `aws:executeAwsApi` - Detach the root volume from the provided instance
1. `aws:assertAwsResourceProperty` - Check the provided instance platform
1. (Instance is Windows):
`aws:executeAwsApi` - Attach the root volume to the EC2Rescue helper instance as \$1xvdf\$1
`aws:sleep` - Sleep 10 seconds
`aws:runCommand` - Run the provided offline script in Powershell
1. (Instance is Linux):
`aws:executeAwsApi` - Attach the root volume to the EC2Rescue helper instance as \$1/dev/sdf\$1
`aws:sleep` - Sleep 10 seconds
`aws:runCommand` - Run the provided offline script in Bash
1. `aws:changeInstanceState` - Stop the EC2Rescue helper instance
1. `aws:changeInstanceState` - Force stop the EC2Rescue helper instance
1. `aws:executeAwsApi` - Detach the root volume from the EC2Rescue helper instance
1. `aws:executeAwsApi` - Attach the root volume back to the provided instance
1. `aws:assertAwsResourceProperty` - Check the CreatePostEC2RescueBackup input value
1. (Create post-EC2Rescue backup) - If \$1CreatePostEC2RescueBackup = true\$1
1. `aws:executeAwsApi` - Create an AMI backup of the provided instance
1. `aws:createTags` - Tag the AMI backup
1. `aws:executeAwsApi` - Restore the initial delete on termination state for the root volume of the provided instance
1. `aws:changeInstanceState` - Restore the initial state of the provided instance (running/stopped)
1. `aws:deleteStack` - Delete the EC2Rescue CloudFormation stack
**Outputs**
runScriptForLinux.Output
runScriptForWindows.Output
preScriptBackup.ImageId
postScriptBackup.ImageId
# `AWSSupport-TroubleshootActiveDirectoryReplication`
**Description**
The **AWSSupport-TroubleshootActiveDirectoryReplication** runbook helps troubleshoot Microsoft Active Directory (AD) domain controller replication failures by checking common settings on a target domain controller instance. This runbook runs a series of PowerShell commands against the provided domain controller instance to check the current replication status and report errors that can potentially cause domain replication issues. The runbook can optionally start replication critical services (`Netlogon`, `RPCSS`, `W32Time`, and `KDC`) if they are stopped and synchronize the system time by running `w32tm /resync /force` on the target instance.
**Important**
AWS Managed Microsoft AD is not in the scope of this runbook.
**Important**
While the automation is running commands on the target instance, changes are made to the target instance file system. These changes include the creation of the log directory (`$env:ProgramData\TroubleshootActiveDirectoryReplication`) and report files.
**How does it work?**
The runbook performs the following checks and actions:
+ Verifies the target instance is running Windows and is managed by Systems Manager.
+ Runs PowerShell scripts to check Active Directory replication configuration and status.
+ Checks security group and network ACL settings for replication partner connectivity.
+ Troubleshoots time synchronization and critical services status.
+ Uploads log files to the specified Amazon S3 bucket for analysis.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootActiveDirectoryReplication)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeInstances`
+ `secretsmanager:GetSecretValu`e
+ `ssm:DescribeInstanceInformation`
+ `ssm:SendCommand`
+ `ssm:GetCommandInvocation`
+ `s3:GetBucketAcl`
+ `s3:GetBucketPolicy`
+ `s3:GetBucketPolicyStatus`
+ `s3:GetBucketPublicAccessBlock`
+ `s3:PutObject`
Example Policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"secretsmanager:GetSecretValue"
"ssm:DescribeInstanceInformation",
"ssm:SendCommand",
"ssm:GetCommandInvocation",
"s3:GetBucketAcl",
"s3:GetBucketPolicy",
"s3:GetBucketPolicyStatus",
"s3:GetBucketPublicAccessBlock",
"s3:PutObject"
],
"Resource": "*"
}
]
}
```
**AWS Secrets Manager setup**
The check replication PowerShell script connects to the target Microsoft Active Directory domain controller by retrieving the username and password with a runtime call to AWS Secrets Manager. Follow the steps in [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html) to create a new AWS Secrets Manager secret. Make sure that the username and password are stored using a key/value pair in the format `{"username":"EXAMPLE-USER","password":"EXAMPLE-PASSWORD"}`. After creating the AWS Secrets Manager secret, make sure you grant the `secretsmanager:GetSecretValue` permission on the secret ARN to your target domain controller IAM instance profile role.
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootActiveDirectoryReplication/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootActiveDirectoryReplication/description) in Systems Manager under Documents.
1. Select **Execute automation**.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
+ 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.
+ Type: `AWS::IAM::Role::Arn`
+ **InstanceId (Required):**
+ Description: (Required) The ID of the Amazon EC2 domain controller instance that you want to troubleshoot Active Directory replication issues. Note that the provided instance has to be a domain controller.
+ Type: `AWS::EC2::Instance::Id`
+ **SecretsManagerArn (Required):**
+ Description: (Required) The ARN of your AWS Secrets Manager secret containing an Active Directory username and password with Enterprise Admin or equivalent permissions to access your Active Directory domain and forest configuration. Make sure that the username and password are stored using a key/value pair in the format `{"username":"EXAMPLE-USER","password":"EXAMPLE-PASSWORD"}`. Make sure to attach the `secretsmanager:GetSecretValue` permission on the secret ARN to your target domain controller IAM instance profile role.
+ Type: `String`
+ Allowed Pattern: `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):secretsmanager:[a-z0-9-]{2,20}:[0-9]{12}:secret:[a-zA-Z0-9]{1}[a-zA-Z0-9\\/_+=.@-]{1,256}$`
+ **TimeSync (Optional):**
+ Description: (Optional) Select `Check` or `Sync`. If you select `Check`, the runbook prints out the current system time sync status. If `Sync` is selected, the runbook will attempt a force time resync by running `w32tm /resync /force` on the target instance.
+ Type: `String`
+ Allowed Values: `[Check, Sync]`
+ Default: `Check`
+ **ServiceAction (Optional):**
+ Description: (Optional) Select `Check` or `Fix`. If you select `Check`, the runbook prints out the current status of the `Netlogon`, `Windows Time service (W32Time)`, `Remote Procedure Call (RPC) Service`, and `Key Distribution Center (KDC)` services. If `Fix` is selected the runbook will attempt to start these services if any is stopped.
+ Type: `String`
+ Allowed Values: `[Check, Fix]`
+ Default: `Check`
+ **LogDestination (Required):**
+ Description: (Required) The Amazon Amazon S3 bucket in your AWS account to upload the command outputs.
+ Type: `String`
1. Select **Execute**.
1. The automation initiates.
1. The document performs the following steps:
+ **assertIfOperatingSystemIsWindows**:
Checks if the operating system of the provided target Amazon EC2 instance is Windows.
+ **assertifInstanceIsSsmManaged**:
Ensures the Amazon EC2 instance is managed by Systems Manager, otherwise the automation ends.
+ **checkReplication**:
Runs a PowerShell script on the specified domain controller instance to get the Active Directory domain replication configuration and status.
+ **checkInstanceSgAndNacl**:
Checks whether traffic to the replication partners are allowed by the security group and network ACL associated to the target domain controller instance.
+ **troubleshootReplication**:
Runs a PowerShell script to troubleshoot time synchronization and critical services status.
+ **verifyS3BucketPublicStatus**:
Checks if the Amazon S3 bucket specified in `LogDestination` allows anonymous, or public read or write access permissions.
+ **`runUploadScript`**:
Runs a PowerShell script to upload the log archive to the AAmazon S3 bucket specified in the `LogDestination` parameter and deletes the archived log file from OS. The log files can be used for troubleshooting or to be shared with AWS Support when troubleshooting replication issues.
1. After completion, review the **Outputs** section for the detailed results of the execution.
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootActiveDirectoryReplication/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSPremiumSupport-TroubleshootEC2DiskUsage`
**Description**
The `AWSPremiumSupport-TroubleshootEC2DiskUsage` runbook helps you investigate and potentially remediate issues with Amazon Elastic Compute Cloud (Amazon EC2) instance root and non-root disk usage. If possible, the runbook attempts to remediate issues by extending the volume and its file system. To perform these tasks, this runbook orchestrates the execution of several runbooks based on the operating system of the affected instance.
The first runbook, `AWSPremiumSupport-DiagnoseDiskUsageOnWindows` or `AWSPremiumSupport-DiagnoseDiskUsageOnLinux`, determines if disk issues can be mitigated by expanding the volume.
The second runbook, `AWSPremiumSupport-ExtendVolumesOnWindows` or `AWSPremiumSupport-ExtendVolumesOnLinux`, uses the output of the first runbook to run Python code that modifies the volume. After the volume has been modified, the runbook extends the partition and file system of the affected volumes.
**Important**
Access to `AWSPremiumSupport-*` runbooks requires a Business \$1 Support, Enterprise Support or Unified Operations Subscription. For more information, see [Compare AWS Support Plans](https://aws.amazon.com/premiumsupport/plans/).
This document was built in collaboration with AWS Managed Services (AMS). AMS helps you manage your AWS infrastructure more efficiently and securely. AMS also provides operational flexibility, enhanced security and compliance, capacity optimization, and cost-savings identification. For more information, see [AWS Managed Services](https://aws.amazon.com/managed-services/).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSPremiumSupport-TroubleshootEC2DiskUsage)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux, Windows
**Parameters**
+ InstanceId
Type: String
Allowed values: ^i-[a-z0-9]\$18,17\$1\$1
Description: (Required) ID of your Amazon EC2 instance.
+ VolumeExpansionEnabled
Type: Boolean
Description: (Optional) Flag to control whether the document will extend the volumes and partitions affected.
Default: true
+ VolumeExpansionUsageTrigger
Type: String
Description: (Optional) Minimum usage of partition space required to trigger extension (in percentage).
Allowed values: ^[0-9]\$11,2\$1\$1
Default: 85
+ VolumeExpansionCapSize
Type: String
Description: (Optional) Maximum size that the Amazon Elastic Block Store (Amazon EBS) volume will be increased to (in GiB).
Allowed values: ^[0-9]\$11,4\$1\$1
Default: 2048
+ VolumeExpansionGibIncrease
Type: String
Description: (Optional) Increase in GiB of the volume. The biggest net increase between VolumeExpansionGibIncrease and VolumeExpansionPercentageIncrease will be used.
Allowed values: ^[0-9]\$11,4\$1\$1
Default: 20
+ VolumeExpansionPercentageIncrease
Type: String
Description: (Optional) Increase in percentage of the volume. The biggest net increase between VolumeExpansionGibIncrease and VolumeExpansionPercentageIncrease will be used.
Allowed values: ^[0-9]\$11,2\$1\$1
Default: 20
+ 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.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeVolumes`
+ `ec2:DescribeVolumesModifications`
+ `ec2:ModifyVolume`
+ `ec2:DescribeInstances`
+ `ec2:CreateImage`
+ `ec2:DescribeImages`
+ `ec2:DescribeTags`
+ `ec2:CreateTags`
+ `ec2:DeleteTags`
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:DescribeAutomationStepExecutions`
+ `ssm:DescribeAutomationExecutions`
+ `ssm:SendCommand`
+ `ssm:DescribeInstanceInformation`
+ `ssm:ListCommands`
+ `ssm:ListCommandInvocations`
**Document Steps**
1. `aws:assertAwsResourceProperty` - Check if the instance is managed by Systems Manager
1. `aws:executeAwsApi` - Describes the instance to get the platform.
1. `aws:branch` - Branches automation based on the instance's platform.
1. If the instance is Windows:
1. `aws:executeAutomation` - Run the `AWSPremiumSupport-DiagnoseDiskUsageOnWindows` runbook in order to diagnose disk usage issues on the instance.
1. `aws:executeAwsApi` - Gets the output of the previous automation.
1. `aws:branch` - Branches based on the output of the diagnostics, and if there are volumes that can be expanded to mitigate the alert.
1. There are no volumes that need to be expanded: End the automation.
1. There are volumes that need to be expanded:
1. `aws:executeAwsApi` - Create an Amazon Machine Image (AMI) of the instance.
1. `aws:waitForAwsResourceProperty` - Waits for the AMI state to be `available`.
1. `aws:executeAutomation` - Run the `AWSPremiumSupport-ExtendVolumesOnWindows` runbook in order to perform the volume modification as well as the required steps in the operating system (OS) to make the new space available.
1. (Platform is not windows) If the input instance is not Windows:
1. `aws:executeAutomation` - Run the `AWSPremiumSupport-DiagnoseDiskUsageOnLinux` runbook in order to diagnose disk usage issues on the instance.
1. `aws:executeAwsApi` - Gets the output of the previous automation.
1. `aws:branch` - Branches based on the output of the diagnostics, and if there are volumes that can be expanded to mitigate the alert.
1. There are no volumes that need to be expanded: End the automation.
1. There are volumes that need to be expanded:
1. `aws:executeAwsApi` - Create an AMI of the instance.
1. `aws:waitForAwsResourceProperty` - Waits for AMI state to be `available`.
1. `aws:executeAutomation` - Run the `AWSPremiumSupport-ExtendVolumesOnLinux` runbook in order to perform the volume modification as well as the required steps in the OS to make the new space available.
**Outputs**
diagnoseDiskUsageAlertOnWindows.Output
extendVolumesOnWindows.Output
diagnoseDiskUsageAlertOnLinux.Output
extendVolumesOnLinux.Output
BackupAMILinux.ImageId
BackupAMIWindows.ImageId
# `AWSSupport-TroubleshootEC2InstanceConnect`
**Description**
`AWSSupport-TroubleshootEC2InstanceConnect` automation helps analyze and detect errors preventing the connection to an Amazon Elastic Compute Cloud (Amazon EC2) instance using [Amazon EC2 Instance Connect](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/connect-linux-inst-eic.html). It identifies issues caused by an unsupported Amazon Machine Image (AMI), missing OS-level package installation or configuration, missing AWS Identity and Access Management (IAM) permissions, or network configuration issues.
**How does it work?**
The runbook takes the Amazon EC2 instance ID, username, connection mode, source IP CIDR, SSH port, and Amazon Resource Name (ARN) for the IAM role or user experiencing issues with Amazon EC2 Instance Connect. It then checks the [prerequisites](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/ec2-instance-connect-prerequisites.html) for connecting to an Amazon EC2 instance using Amazon EC2 Instance Connect:
+ The instance is running and in a healthy state.
+ The instance is located in an AWS region supported by Amazon EC2 Instance Connect.
+ AMI of the instance is supported by Amazon EC2 Instance Connect.
+ The instance can reach the Instance Metadata Service (IMDSv2).
+ Amazon EC2 Instance Connect package is properly installed and configured at the OS level.
+ The network configuration (security groups, network ACL, and route table rules) allows connection to the instance through Amazon EC2 Instance Connect.
+ The IAM role or user that's used to leverage Amazon EC2 Instance Connect has access to push keys to the Amazon EC2 instance.
**Important**
To check the instance AMI, IMDSv2 reachability, and Amazon EC2 Instance Connect package installation, the instance must be SSM managed. Otherwise, it skips those steps. For more information, see [Why is my Amazon EC2 instance not displaying as a managed node.](https://repost.aws/knowledge-center/systems-manager-ec2-instance-not-appear)
The network check will only detect if security group and network ACL rules block traffic when SourceIpCIDR is provided as an input parameter. Otherwise, it will only display SSH-related rules.
Connections using [Amazon EC2 Instance Connect Endpoint](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/connect-using-eice.html) are not validated in this runbook.
For private connections, the automation does not check if the SSH client is installed on the source machine and if it can reach the instance's private IP address.
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeInstances`
+ `ec2:DescribeSecurityGroups`
+ `ec2:DescribeNetworkAcls`
+ `ec2:DescribeRouteTables`
+ `ec2:DescribeInternetGateways`
+ `iam:SimulatePrincipalPolicy`
+ `ssm:DescribeInstanceInformation`
+ `ssm:ListCommands`
+ `ssm:ListCommandInvocations`
+ `ssm:SendCommand`
**Instructions**
Follow these steps to configure the automation:
1. Navigate to the [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootEC2InstanceConnect/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootEC2InstanceConnect/description) in the AWS Systems Manager console.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **InstanceId (Required):**
The ID of the target Amazon EC2 instance that you could not connect to using Amazon EC2 Instance Connect.
+ **AutomationAssumeRole (Optional):**
The ARN of the 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 who starts this runbook.
+ **Username (Required):**
The username used to connect to the Amazon EC2 instance using Amazon EC2 Instance Connect. It is used to evaluate if IAM access is granted for this particular user.
+ **EC2InstanceConnectRoleOrUser (Required):**
The ARN of the IAM role or user that is leveraging Amazon EC2 Instance Connect to push keys to the instance.
+ **SSHPort (Optional):**
The SSH port configured on the Amazon EC2 instance. Default value is `22`. The port number must be between `1-65535`.
+ **SourceNetworkType (Optional):**
The network access method to the Amazon EC2 instance:
+ **Browser:** You connect from the AWS Management Console.
+ **Public:** You connect to the instance located in a public subnet over the internet (for example, your local computer).
+ **Private:** You connect through the instance's private IP address.
+ **SourceIpCIDR (Optional):**
The source CIDR that includes the IP address of the device (such as your local computer) you will log from using Amazon EC2 Instance Connect. Example: 172.31.48.6/32. If no value is provided with public or private access mode, the runbook will not evaluate if the Amazon EC2 instance security group and network ACL rules allow SSH traffic. It will display SSH-related rules instead.
![\[Input parameters form for EC2 Instance Connect troubleshooting with various fields.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-ec2-instance-connect_input_parameters.png)
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **AssertInitialState:**
Ensures that the Amazon EC2 instance status is running. Otherwise, the automation ends.
+ **GetInstanceProperties:**
Gets the current Amazon EC2 instance properties (PlatformDetails, PublicIpAddress, VpcId, SubnetId and MetadataHttpEndpoint).
+ **GatherInstanceInformationFromSSM:**
Gets the Systems Manager instance's ping status and operating system details if the instance is SSM managed.
+ **CheckIfAWSRegionSupported:**
Checks if the Amazon EC2 instance is located in an Amazon EC2 Instance Connect supported AWS region.
+ **BranchOnIfAWSRegionSupported:**
Continues the execution if the AWS Region is supported by Amazon EC2 Instance Connect. Otherwise, it creates the output and exits the automation.
+ **CheckIfInstanceAMIIsSupported:**
Checks if the AMI associated with the instance is supported by Amazon EC2 Instance Connect.
+ **BranchOnIfInstanceAMIIsSupported:**
If the instance AMI is supported, it performs the OS-level checks, like metadata reachability and Amazon EC2 Instance Connect package installation and configuration. Otherwise, it checks if HTTP metadata is enabled using AWS API, then advances to the network check step.
+ **CheckIMDSReachabilityFromOs:**
Runs a Bash script on the target Amazon EC2 Linux instance to check if it is able to reach the IMDSv2.
+ **CheckEICPackageInstallation:**
Runs a Bash script on the target Amazon EC2 Linux instance to check if the Amazon EC2 Instance Connect package is properly installed and configured.
+ **CheckSSHConfigFromOs:**
Runs a Bash script on the target Amazon EC2 Linux instance to check if the configured SSH port matches the input parameter `SSHPort.`
+ **CheckMetadataHTTPEndpointIsEnabled:**
Checks if the instance metadata service HTTP endpoint is enabled.
+ **CheckEICNetworkAccess:**
Checks if the network configuration (security groups, network ACL, and route table rules) allows connection to the instance through Amazon EC2 Instance Connect.
+ **CheckIAMRoleOrUserPermissions:**
Checks if the IAM role or user used to leverage Amazon EC2 Instance Connect has access to push keys to the Amazon EC2 instance using the provided username.
+ **MakeFinalOutput:**
Consolidates the output of all previous steps.
1. After completed, review the **Outputs** section for the detailed results of the execution:
Execution where the target instance has all required prerequisites:
![\[EC2 Instance Connect prerequisites check results showing successful validations for various configurations.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-ec2-instance-connect_outputs_all_requirements_found.png)
Execution where the AMI of the target instance is not supported:
![\[Error message indicating EC2 Instance Connect does not support the specified AMI version.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-ec2-instance-connect_outputs_all_requirements_not_found.png)
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootEC2InstanceConnect/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows landing page](https://aws.amazon.com/premiumsupport/technology/saw/)
AWS service documentation
+ [How do I troubleshoot issues connecting to my Amazon EC2 instance using Amazon EC2 Instance Connect?](https://repost.aws/knowledge-center/ec2-instance-connect-troubleshooting)
# `AWSSupport-TroubleshootLinuxMGNDRSAgentLogs`
**Description**
`AWSSupport-TroubleshootLinuxMGNDRSAgentLogs` automation runbook is used to detect common errors when installing the AWS Application Migration Service (AWS MGN) and AWS Elastic Disaster Recovery (AWS DRS) replication agents in Linux servers to migrate source servers to the AWS cloud.
**How does it work?**
The runbook `AWSSupport-TroubleshootLinuxMGNDRSAgentLogs` takes the Amazon Simple Storage Service (Amazon S3) path where the AWS MGN or AWS DRS installation log `aws_replication_agent_installer.log` is uploaded as parameter. Then, it performs the following tasks:
+ **Validation:** Checks if the provided log file is valid and that it contains at least one agent installation.
+ **Parsing:** Thoroughly parses the latest agent installation in the log file for known AWS MGN or AWS DRS errors.
+ **Error Detection and resolution:** Based on the parsing, it detects and lists any errors or issues during the agent installation process. For each detected error, the runbook provides detailed steps to help resolve or mitigate the issue.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootLinuxMGNDRSAgentLogs)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `s3:GetObject`
+ `s3:ListBucket`
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootLinuxMGNDRSAgentLogs/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootLinuxMGNDRSAgentLogs/description) in Systems Manager under Documents.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
The Amazon Resource Name (ARN) of the AWS 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 who starts this runbook.
+ **BucketName (Required):**
The name of the Amazon S3 bucket where the replication agent log is stored.
+ **S3ObjectKey (Required):**
The key of the Amazon S3 object where the replication agent installer log file is stored. Example: If the Amazon S3 URI is `s3://bucket_name/path/to/file/aws_replication_agent_installer.log`, then you should input `path/to/file/aws_replication_agent_installer.log`.
+ **ServiceName (Required):**
The name of the service for which the replication agent is installed. Allowed values: `AWS MGN` or `AWS DRS`
![\[Input parameters form for AWS replication agent with fields for role, bucket name, object key, and service.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/automation-troublshoot-linux-mngdrs-agent-logs_input_parameters.png)
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **`ValidateInput`**
Ensures that the replication agent log file is valid and accessible using the provided Amazon S3 bucket name and path to the object, then returns the byte number of the latest agent installation.
+ **`CheckReplicationAgentLogErrors`**
Reads the replication agent log file starting from the latest installation byte and search for known AWS MGN or AWS DRS errors.
+ **`MakeFinalOutput`**
Creates the output from the previous checks including information about the errors found and troubleshooting recommendations.
1. After completed, review the Outputs section for the detailed results of the execution:
![\[Output showing validation step, error detection, and troubleshooting steps for kernel package installation.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/automation-troublshoot-linux-mngdrs-agent-logs_outputs.png)
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootLinuxMGNDRSAgentLogs/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows landing page](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSSupport-TroubleshootRDP`
**Description**
The `AWSSupport-TroubleshootRDP` runbook allows the user to check or modify common settings on the target instance which may impact Remote Desktop Protocol (RDP) connections, such as the RDP port, Network Layer Authentication (NLA) and Windows Firewall profiles. Optionally, changes can be applied offline by stopping and starting the instance, if the user explicitly allows for offline remediation. By default, the runbook reads and outputs the values of the settings.
**Important**
Changes to the RDP settings, RDP service and Windows Firewall profiles should be carefully reviewed before using this runbook.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootRDP)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
+ Action
Type: String
Valid values: CheckAll \$1 FixAll \$1 Custom
Default: Custom
Description: (Optional) [Custom] Use the values from Firewall, RDPServiceStartupType, RDPServiceAction, RDPPortAction, NLASettingAction and RemoteConnections to manage the settings. [CheckAll] Read the values of the settings without changing them. [FixAll] Restore RDP default settings, and disable the Windows Firewall.
+ AllowOffline
Type: String
Valid values: true \$1 false
Default: false
Description: (Optional) Fix only - Set it to true if you allow an offline RDP remediation in case the online troubleshooting fails, or the provided instance is not a managed instance. Note: For the offline remediation, SSM Automation stops the instance, and creates an AMI before attempting any operations.
+ 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.
+ Firewall
Type: String
Valid values: Check \$1 Disable
Default: Check
Description: (Optional) Check or disable the Windows firewall (all profiles).
+ InstanceId
Type: String
Description: (Required) The ID of the instance to troubleshoot the RDP settings of.
+ NLASettingAction
Type: String
Valid values: Check \$1 Disable
Default: Check
Description: (Optional) Check or disable Network Layer Authentication (NLA).
+ RDPPortAction
Type: String
Valid values: Check \$1 Modify
Default: Check
Description: (Optional) Check the current port used for RDP connections, or modify the RDP port back to 3389 and restart the service.
+ RDPServiceAction
Type: String
Valid values: Check \$1 Start \$1 Restart \$1 Force-Restart
Default: Check
Description: (Optional) Check, start, restart, or force-restart the RDP service (TermService).
+ RDPServiceStartupType
Type: String
Valid values: Check \$1 Auto
Default: Check
Description: (Optional) Check or set the RDP service to automatically start when Windows boots.
+ RemoteConnections
Type: String
Valid values: Check \$1 Enable
Default: Check
Description: (Optional) An action to perform on the fDenyTSConnections setting: Check, Enable.
+ S3BucketName
Type: String
Description: (Optional) Offline only - 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.
+ SubnetId
Type: String
Default: SelectedInstanceSubnet
Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the offline troubleshooting. If no subnet ID is specified, AWS Systems Manager Automation will create a new VPC. IMPORTANT: The subnet must be in the same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
It is recommended that the EC2 instance receiving the command has an IAM role with the **AmazonSSMManagedInstanceCore** Amazon managed policy attached. For the online remediation, the user must have at least **ssm:DescribeInstanceInformation**, **ssm:StartAutomationExecution** and **ssm:SendCommand** to run the automation and send the command to the instance, plus **ssm:GetAutomationExecution** to be able to read the automation output. For the offline remediation, the user must have at least **ssm:DescribeInstanceInformation**, **ssm:StartAutomationExecution**, **ec2:DescribeInstances**, plus **ssm:GetAutomationExecution** to be able to read the automation output. `AWSSupport-TroubleshootRDP` calls `AWSSupport-ExecuteEC2Rescue` to perform the offline remediation - please review the permissions for `AWSSupport-ExecuteEC2Rescue` to ensure you can run the automation successfully.
**Document Steps**
1. `aws:assertAwsResourceProperty` - Check if the instance is a Windows Server instance
1. `aws:assertAwsResourceProperty` - Check if the instance is a managed instance
1. (Online troubleshooting) If the instance is a managed instance, then:
1. `aws:assertAwsResourceProperty` - Check the provided Action value
1. (Online check) If the **Action = CheckAll**, then:
`aws:runPowerShellScript` - Runs the PowerShell script to get the Windows Firewall profiles status.
`aws:executeAutomation` - Calls `AWSSupport-ManageWindowsService` to get the RDP service status.
`aws:executeAutomation` - Calls `AWSSupport-ManageRDPSettings` to get the RDP settings.
1. (Online fix) If the **Action = FixAll**, then:
`aws:runPowerShellScript` - Runs the PowerShell script to disable all Windows Firewall profiles.
`aws:executeAutomation` - Calls `AWSSupport-ManageWindowsService` to start the RDP service.
`aws:executeAutomation` - Calls `AWSSupport-ManageRDPSettings` to enable remote connections and disable NLA.
1. (Online management) If the **Action = Custom**, then:
`aws:runPowerShellScript` - Runs the PowerShell script to manage the Windows Firewall profiles.
`aws:executeAutomation` - Calls `AWSSupport-ManageWindowsService` to manage the RDP service.
`aws:executeAutomation` - Calls `AWSSupport-ManageRDPSettings` to manage the RDP settings.
1. (Offline remediation) If the instance is not a managed instance then:
1. `aws:assertAwsResourceProperty` - Assert **AllowOffline = true**
1. `aws:assertAwsResourceProperty` - Assert **Action = FixAll**
1. `aws:assertAwsResourceProperty` - Assert the value of SubnetId
(Use the provided instance's subnet) If SubnetId is SELECTED\$1INSTANCE\$1SUBNET
`aws:executeAwsApi` - Retrieve the current instance's subnet.
`aws:executeAutomation` - Run `AWSSupport-ExecuteEC2Rescue` with provided instance's subnet.
1. (Use the provided custom subnet) If SubnetId is not SELECTED\$1INSTANCE\$1SUBNET
`aws:executeAutomation` - Run `AWSSupport-ExecuteEC2Rescue` with provided SubnetId value.
**Outputs**
manageFirewallProfiles.Output
manageRDPServiceSettings.Output
manageRDPSettings.Output
checkFirewallProfiles.Output
checkRDPServiceSettings.Output
checkRDPSettings.Output
disableFirewallProfiles.Output
restoreDefaultRDPServiceSettings.Output
restoreDefaultRDPSettings.Output
troubleshootRDPOffline.Output
troubleshootRDPOfflineWithSubnetId.Output
# `AWSSupport-TroubleshootSSH`
**Description**
The `AWSSupport-TroubleshootSSH` runbook installs the Amazon EC2Rescue tool for Linux, and then uses the EC2Rescue tool to check or attempt to fix common issues that prevent a remote connection to the Linux machine via SSH. Optionally, changes can be applied offline by stopping and starting the instance, if the user explicitly allows for offline remediation. By default, the runbook operates in read-only mode.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootSSH)
For information about working with the `AWSSupport-TroubleshootSSH` runbook, see this [`AWSSupport-TroubleshootSSH` troubleshooting topic](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-ssh-errors-automation-workflow/) from AWS Premium Support.
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ Action
Type: String
Valid values: CheckAll \$1 FixAll
Default: CheckAll
Description: (Required) Specify whether to check for issues without fixing them or to check and automatically fix any discovered issues.
+ AllowOffline
Type: String
Valid values: true \$1 false
Default: false
Description: (Optional) Fix only - Set it to true if you allow an offline SSH remediation in case the online troubleshooting fails, or the provided instance is not a managed instance. Note: For the offline remediation, SSM Automation stops the instance, and creates an AMI before attempting any operations.
+ 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.
+ InstanceId
Type: String
Description: (Required) ID of your EC2 instance for Linux.
+ S3BucketName
Type: String
Description: (Optional) Offline only - 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.
+ SubnetId
Type: String
Default: SelectedInstanceSubnet
Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the offline troubleshooting. If no subnet ID is specified, AWS Systems Manager Automation will create a new VPC.
**Important**
The subnet must be in the same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
It is recommended that the EC2 instance receiving the command has an IAM role with the **AmazonSSMManagedInstanceCore** Amazon managed policy attached. For the online remediation, the user must have at least **ssm:DescribeInstanceInformation**, **ssm:StartAutomationExecution** and **ssm:SendCommand** to run the automation and send the command to the instance, plus **ssm:GetAutomationExecution** to be able to read the automation output. For the offline remediation, the user must have at least **ssm:DescribeInstanceInformation**, **ssm:StartAutomationExecution**, **ec2:DescribeInstances**, plus **ssm:GetAutomationExecution** to be able to read the automation output. `AWSSupport-TroubleshootSSH` calls `AWSSupport-ExecuteEC2Rescue` to perform the offline remediation - please review the permissions for `AWSSupport-ExecuteEC2Rescue` to ensure you can run the automation successfully.
**Document Steps**
1. `aws:assertAwsResourceProperty` - Check if the instance is a managed instance
1. (Online remediation) If the instance is a managed instance, then:
1. `aws:configurePackage` - Install EC2Rescue for Linux via `AWS-ConfigureAWSPackage`.
1. `aws:runCommand` - Run the bash script to run EC2Rescue for Linux.
1. (Offline remediation) If the instance is not a managed instance then:
1. `aws:assertAwsResourceProperty` - Assert **AllowOffline = true**
1. `aws:assertAwsResourceProperty` - Assert **Action = FixAll**
1. `aws:assertAwsResourceProperty` - Assert the value of SubnetId
1. (Use the provided instance's subnet) If SubnetId is SelectedInstanceSubnet us `aws:executeAutomation` to run `AWSSupport-ExecuteEC2Rescue` with provided instance's subnet.
1. (Use the provided custom subnet) If SubnetId is not SelectedInstanceSubnet use `aws:executeAutomation` to run `AWSSupport-ExecuteEC2Rescue` with provided SubnetId value.
**Outputs**
troubleshootSSH.Output
troubleshootSSHOffline.Output
troubleshootSSHOfflineWithSubnetId.Output
# `AWSSupport-TroubleshootSUSERegistration`
**Description**
The `AWSSupport-TroubleshootSUSERegistration` runbook helps you to identify why registering an Amazon Elastic Compute Cloud (Amazon EC2) SUSE Linux Enterprise Server instance with SUSE Update Infrastructure failed. The automation output provides steps to resolve, or helps you troubleshoot, the issue. If the instance passes all checks during the automation, the instance is registered with SUSE Update Infrastructure.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootSUSERegistration)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Linux
**Parameters**
+ 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.
+ InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 instance you want to troubleshoot.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:DescribeInstanceProperties`
+ `ssm:DescribeInstanceInformation`
+ `ssm:ListCommandInvocations`
+ `ssm:SendCommand`
+ `ssm:ListCommands`
**Document Steps**
+ `aws:assertAwsResourceProperty` - Checks if the Amazon EC2 instance is managed by AWS Systems Manager.
+ `aws:runCommand` - Checks if the Amazon EC2 instance platform is SLES.
+ `aws:runCommand` - Checks if the package `cloud-regionsrv-client` version is greater than or equal to the required version 9.0.10.
+ `aws:runCommand` - Checks if the symbolic link for base product is broken, and fixes the link it it is broken.
+ `aws:runCommand` - Checks if the hosts file (`/etc/hosts`) contains records for `smt-ec2-suscloud.net`. The automation removes any duplicate entries.
+ `aws:runCommand` - Checks if the `curl` command is installed.
+ `aws:runCommand` - Checks if the Amazon EC2 instance can access the Instance Metadata Service (IMDS) address 169.254.169.254.
+ `aws:runCommand` - Checks if the Amazon EC2 instance has a billing code or AWS Marketplace product code.
+ `aws:runCommand` - Checks if the Amazon EC2 instance can reach at least 1 regional server over HTTPS.
+ `aws:runCommand` - Checks if the Amazon EC2 instance can reach the Subscription Management Tool (SMT) servers over HTTP.
+ `aws:runCommand` - Checks if the Amazon EC2 instance can reach the Subscription Management Tool (SMT) servers over HTTPS.
+ `aws:runCommand` - Checks if the Amazon EC2 instance can reach the `smt-ec2.susecloud.net` address over HTTPS.
+ `aws:runCommand` - Registers the Amazon EC2 instance with SUSE Update Infrastructure.
+ `aws:executeScript` - Gathers and outputs the output of all the previous steps.
# `AWSSupport-TroubleshootWindowsPerformance`
**Description**
The runbook `AWSSupport-TroubleshootWindowsPerformance` helps troubleshoot ongoing performance issues on Amazon Elastic Compute Cloud (Amazon EC2) Windows instance. The runbook captures logs from the target instance and analyzes CPU, memory, disk, and network performance metrics. Optionally, the automation can capture a process dump to help you determine the potential cause of performance degradation. The automation also captures the event and system logs by using the latest [https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/Windows-Server-EC2Rescue.html](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/Windows-Server-EC2Rescue.html) tool, if you allow this runbook to install it.
**How does it work?**
The runbook performs the following steps:
+ Checks the Amazon EC2 instance for prerequisites.
+ Generates performance logs in the root disk of the Amazon EC2 Windows instance
+ Stores captured logs in folder `C:\ProgramData\Amazon\SSM\TroubleshootWindowsPerformance`
+ If an Amazon Simple Storage Service (Amazon S3) bucket is provided, and the automation assume role has the required permissions, the captured logs are uploaded to the Amazon S3 bucket.
+ Installs the latest `EC2Rescue` tool to the Amazon EC2 Windows instance to capture events and system logs if you choose to install it, but it does not analyze the process dump and logs captured by `EC2Rescue`.
**Important**
To execute this runbook, the Amazon EC2 Windows instance must be managed by AWS Systems Manager. For more information, see [Why is my Amazon EC2 instance not displaying as a managed node](https://repost.aws/knowledge-center/systems-manager-ec2-instance-not-appear).
To execute this runbook, the Amazon EC2 Windows instance must be running on versions Windows 8.1 / Windows Server 2012 R2 (6.3) or newer with PowerShell 4.0 or above. For more information, see [Windows Operating System version](https://learn.microsoft.com/en-us/windows/win32/sysinfo/operating-system-version).
For the generation of performance logs, at least 10 GB of free space on the root device is required. If the root disk is larger than 100 GB, the free space must be greater than 10% of the disk size. If you dump a process during execution, the free space must be greater than 10 GB plus the total memory size consumed by the process when the process consumes more than 10 GB memory.
The logs generated on the root device are not deleted automatically.
The runbook does not uninstall the `EC2Rescue` tool. For more information, see [Use `EC2Rescue` for Windows Server](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/Windows-Server-EC2Rescue.html).
It is best practice to run this automation during a performance impact. You can also run it periodically using an AWS Systems Manager State Manager association or by scheduling AWS Systems Manager Maintenance Windows.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootWindowsPerformance)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ec2:DescribeInstances`
+ `ssm:DescribeAutomationExecutions`
+ `ssm:DescribeInstanceInformation`
+ `ssm:GetAutomationExecution`
+ `ssm:ListCommands`
+ `ssm:ListCommandInvocations`
+ `ssm:SendCommand`
+ `s3:ListBucket`
+ `s3:GetEncryptionConfiguration`
+ `s3:GetBucketPublicAccessBlock`
+ `s3:GetBucketPolicyStatus`
+ `s3:PutObject`
+ `s3:GetBucketAcl`
+ `s3:GetAccountPublicAccessBlock`
*(Optional) The IAM role attached on the instance profile or IAM user configured on the instance requires the following actions to upload logs to the Amazon S3 bucket specified for parameter `LogUploadBucketName`:*
+ `s3:PutObject`
+ `s3:GetObject`
+ `s3:ListBucket`
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootWindowsPerformance/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootWindowsPerformance/description) in Systems Manager under Documents.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
The Amazon Resource Name (ARN) of the AWS 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 who starts this runbook.
+ **InstanceId (Required):**
The ID of the target Amazon EC2 Windows instance where you want to run the automation. The instance must be managed by Systems Manager to execute the automation.
+ **CaptureProcessDump (Optional):**
The process dump type to capture. The automation can capture one process dump for the process that is potentially causing the performance impact in the beginning of the automation. The instance root volume requires at least 10 GB free space (greater than 10% of the disk size when the root volume size is bigger than 100 GB, and 10 GB plus the total memory size consumed by the process when the process consumes more than 10 GB memory).
+ **LogCaptureDuration (Optional):**
The number of minutes, between `1` and `15`, that this automation will capture logs while the issue is present. Default is `5`.
+ **LogUploadBucketName (Optional):**
The Amazon S3 bucket in your account where you want to upload the logs. The bucket must be configured with server-side encryption (SSE), and the bucket policy must not grant unnecessary read/write permissions to parties that do not need access to the captured logs. The Amazon EC2 Windows instance must have access to the Amazon S3 bucket.
+ **InstallEC2RescueTool (Optional):**
Set to `Yes` to allow the runbook to install the latest version of the `EC2Rescue` tool to capture the Windows Events and System logs. Default is `No`.
+ **Acknowledgement (Required):**
Read the complete details of the actions performed by this automation runbook and if you agree, type `Yes, I understand and acknowledge`.
![\[Input parameters form for troubleshooting Amazon EC2 Windows instance performance issues.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-windows-performance_input_parameters.png)
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **`CheckConcurrency:`**
Ensures that there is only one execution of this runbook targeting the instance. If the runbook finds another execution targeting the same instance, it returns an error and ends.
+ **`AssertInstanceIsWindows:`**
Asserts that the Amazon EC2 instance is running on Windows Operating System. Otherwise, the automation ends.
+ **`AssertInstanceIsManagedInstance:`**
Asserts that the Amazon EC2 instance is managed by AWS Systems Manager. Otherwise the automation ends.
+ **`VerifyPrerequisites:`**
Verifies the PowerShell version on the instance OS and ensures that the instance can be connected through Systems Manager to run PowerShell commands. This automation supports PowerShell 4.0 and above running on versions Windows 8.1 / Server 2012 R2 (6.3) or newer. If the version is older, the automation fails. When you choose to upload logs to Amazon S3 bucket, this automation Checks that the AWS Tools for PowerShell module is available. If not, the automation ends.
+ **`BranchOnProcessDump:`**
Branches based on if you set it to capture the dump of processes that impacted performance.
+ **`CaptureProcessDump:`**
Checks if the instance has enough space to run this automation (when you choose Highest CPU / Memory).
+ **`CapturePerformanceLogs:`**
Checks the disk space again and runs the PowerShell script on the instance to create perfmon counters and start Performance Monitor and Windows Performance Recorder logging. The script stops after the defined `LogCaptureDuration` is met.
+ **`SummarizePerformanceLogs:`**
Summarizes the XML report generated on the previous step, `CapturePerformanceLogs`, to find the responsible process consuming the most WorkingSet64 (Memory) and % Processor Time (CPU) shown as output on the automation. It generates similar information for usage of LogicalDisk, Network Interface, Memory, TCPv4, IPv4, and UDPv4 and saves it to `analysis_output.log` in the output folder.
+ **`BranchOnInstallEC2Rescue:`**
Branches if you set it to install the latest `EC2Rescue` tool in the Amazon EC2 instance.
+ **`InstallEC2RescueTool:`**
Installs the `EC2Rescue` tool in the instance OS to capture `EC2Rescue` logs using `AWS-ConfigureAWSPackage`.
+ **`RunEC2RescueTool:`**
Runs the `EC2Rescue` tool in the instance OS to capture all logs needed. `EC2Rescue` captures only the required logs to save space.
+ **`BranchOnIfS3BucketProvided:`**
Branches based on user input of `LogUploadBucketName` to see if there is a bucket name available to upload logs.
+ **`GetS3BucketPublicStatus:`**
Determines if an Amazon S3 bucket is provided, and if so, confirms that the Amazon S3 bucket is not public and is configured with SSE.
+ **`UploadLogResult:`**
Uploads the logs to the Amazon S3 bucket provided. If the PowerShell version is 5.0 or above, it compresses the logs to a ZIP archive and uploads them. It deletes the ZIP file after upload completes. If the PowerShell version is below 5.0, it uploads the files directly to a folder.
+ **`CleanUpLogsOnFailure:`**
Cleans all the logs generated by the `CapturePerformanceLogs` step when it fails. The `CleanUpLogsOnFailure` step may fail or timeout if SSM Agent isn't working correctly, or the Windows system is unresponsive.
1. After completed, review the Outputs section for the detailed results of the execution:
Execution where the target instance has all required prerequisites.
![\[Output logs showing performance capture process, EC2Rescue completion, and top CPU/memory usage processes.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-windows-performance_outputs_all_prerequisites_met.png)
Execution where the target instance is on Linux platform and the execution failed. You would select the step ID to see the failure details.
![\[Execution status showing failed overall status with 2 executed steps, 1 succeeded and 1 failed.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-windows-performance_outputs_failed_linux_instance.png)
The failure details of step `AssertInstanceIsWindows`.
![\[Failure details showing verification error for Linux property value instead of Windows.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-windows-performance_outputs_assert_windows_fail.png)
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootWindowsPerformance/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows landing page](https://aws.amazon.com/premiumsupport/technology/saw/)
# `AWSSupport-TroubleshootWindowsUpdate`
**Description**
The `AWSSupport-TroubleshootWindowsUpdate` runbook is used to identify issues that could fail the Windows updates for Amazon Elastic Compute Cloud (Amazon EC2) Windows instances.
**How does it work?**
The runbook performs the following steps:
+ Checks if the target Amazon EC2 instance is managed by AWS Systems Manager.
+ Checks if the AWS Systems Manager Agent (SSM Agent) and Windows Server versions are supported for Systems Manager patching operations.
+ Checks the available disk space recommended for Windows updates and if a reboot is pending. A pending reboot normally indicates that updates are pending, and a reboot is required before performing additional updates.
+ Configures the proxy settings at the operating system level, which can help troubleshoot connectivity issues.
+ Performs an Amazon Simple Storage Service (Amazon S3) endpoint connectivity test and calls the [https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_GetDeployablePatchSnapshotForInstance.html](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_GetDeployablePatchSnapshotForInstance.html) API operation to retrieve the current snapshot for the patch baseline the managed node uses.
+ If the connection fails, provides the option to run the `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2` runbook to analyze the instance's connectivity to Amazon S3 endpoints.
+ Validates the Windows updates configuration and tests Windows Server Update Services (WSUS) (if applicable).
**Important**
Active Directory domain controllers are not supported.
Windows Server version 2008 R2 or previous versions are not supported.
SSM Agent 1.2.371 or previous versions are not supported.
The `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2` runbook uses [https://docs.aws.amazon.com//vpc/latest/reachability/what-is-reachability-analyzer.html](https://docs.aws.amazon.com//vpc/latest/reachability/what-is-reachability-analyzer.html) to analyze the network connectivity between a source and a service endpoint. You are charged per analysis run between a source and destination. For more details, see [Amazon VPC Pricing](https://aws.amazon.com/vpc/pricing/).
The `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2` runbook is not available in all regions where Systems Manager is supported.
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-TroubleshootWindowsUpdate)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
+ `ssm:StartAutomationExecution`
+ `ssm:GetAutomationExecution`
+ `ssm:DescribeInstanceInformation`
+ `ssm:SendCommand`
+ `ssm:ListCommandInvocations`
+ `ssm:ListCommands`
**Note**
To run the child runbook `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2`, add the permissions listed in [this document](https://docs.aws.amazon.com//systems-manager-automation-runbooks/latest/userguide/automation-awssupport-analyzeawsendpointreachabilityfromec2.html).
**Instructions**
Follow these steps to configure the automation:
1. Navigate to [https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootWindowsUpdate/description](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootWindowsUpdate/description) in Systems Manager under Documents.
1. Select Execute automation.
1. For the input parameters, enter the following:
+ **AutomationAssumeRole (Optional):**
The Amazon Resource Name (ARN) of the AWS 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 who starts this runbook.
+ **InstanceId (Required):**
Enter the ID of the Amazon EC2 instance where the Windows update failed.
+ **RunVpcReachabilityAnalyzer (Optional):**
Specify `true` to run the `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2` automation if a network issue is determined by the extended checks or if the instance ID specified is not a managed instance. For more information on this child automation, refer to the [documentation](https://docs.aws.amazon.com//systems-manager-automation-runbooks/latest/userguide/automation-awssupport-analyzeawsendpointreachabilityfromec2.html). The default value is `false`.
+ **RetainVpcReachabilityAnalysis (Optional):**
Only relevant if `RunVpcReachabilityAnalyzer` is `true`. Specify `true` to retain the network insight path and related analyses created by `Reachability Analyzer`. By default, those resources are deleted after successful analysis. If you choose to retain the analysis, the child runbook does not delete the analysis and you can visualize it in the Amazon VPC console. The console link will be available in the child automation output. The default value `false`.
![\[Input parameters form for an AWS EC2 instance with fields for InstanceId and automation options.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-windows-update_input_parameters.png)
1. Select Execute.
1. The automation initiates.
1. The document performs the following steps:
+ **`getWindowsServerAndSSMAgentVersion:`**
Verifies that the target instance is managed by AWS Systems Manager and gets details about the SSM Agent version and Windows version.
+ **`assertifInstanceIsSsmManaged:`**
Ensures the Amazon EC2 instance is managed by AWS Systems Manager (SSM), otherwise the automation ends.
+ **`CheckProxy:`**
Checks for all proxy types for the Windows instance.
+ **`CheckPrerequisites:`**
Gets the SSM Agent version and Windows version, and determines if it is an Active Directory Domain Controller (DC). If the instance is a DC or the SSM Agent or Windows version is not supported, the runbook stops.
+ **`CheckDiskSpace:`**
Gets and validates the available disk space over the Windows instance if it is sufficient for performing the Windows update.
+ **`CheckPendingReboot:`**
Checks for any pending reboot over the Windows instance.
+ **`CheckS3Connectivity:`**
Checks if the instance can reach the Amazon S3 endpoints for `Patchbaseline`.
+ **`branchOnRunVpcReachabilityAnalyzer:`**
If `RunVpcReachabilityAnalyzer` is true, then it branches the automation to run deeper analysis for the debugging Amazon S3 connectivity.
+ **`GenerateEndpoints:`**
Generates an endpoint to have an extended connectivity check for the Amazon S3 endpoint.
+ **`analyzeAwsEndpointReachabilityFromEC2:`**
Calls the automation runbook, `AWSSupport-AnalyzeAWSEndpointReachabilityFromEC2`. to check the reachability of the selected instance to the required endpoints.
+ **`CheckWindowsUpdateServices:`**
Checks the Windows Update service status and start type.
+ **`CheckWindowsUpdateSettings:`**
Checks for Windows Update policies configured over the Windows instance.
+ **`CheckWSUSSettings:`**
Checks whether the Windows update is configured with WSUS or Microsoft Update Catalog and verifies connectivity.
+ **`CheckWUGlobalSettings:`**
Checks the Windows Update global settings configured over the Windows instance.
+ **`GenerateLogs:`**
Downloads Windows Update logs and CBS logs onto the instance desktop and checks Windows event logs for failure.
+ **`FinalReport:`**
Generates a complete report of all steps.
1. After completed, review the Outputs section for the detailed results of the execution:
![\[Final report results showing various system checks and statuses, all marked as PASSED.\]](http://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/images/awssupport-troubleshoot-windows-update_outputs.png)
**References**
Systems Manager Automation
+ [Run this Automation (console)](https://console.aws.amazon.com/systems-manager/documents/AWSSupport-TroubleshootWindowsUpdate/description)
+ [Run an automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-working-executing.html)
+ [Setting up an Automation](https://docs.aws.amazon.com//systems-manager/latest/userguide/automation-setup.html)
+ [Support Automation Workflows landing page](https://aws.amazon.com/premiumsupport/technology/saw/)
Documentation related to the AWS service
+ Refer to the article, [TroubleShoot Windows Update](https://repost.aws/knowledge-center/ec2-windows-update-troubleshoot), for more information.
# `AWSSupport-UpgradeWindowsAWSDrivers`
**Description**
The `AWSSupport-UpgradeWindowsAWSDrivers` runbook upgrades or repairs storage and network AWS drivers on the specified EC2 instance. The runbook attempts to install the latest versions of AWS drivers online by calling SSM Agent. If SSM Agent is not contactable, the runbook can perform an offline installation of the AWS drivers if explicitly requested.
This runbook supports the following operating systems:
+ Windows Server 2016
+ Windows Server 2019
+ Windows Server 2022
+ Windows Server 2025
**Note**
Both the online and offline upgrade will create an AMI before attempting any operations, which will persist after the automation completes. It is your responsibility to secure access to the AMI, or to delete it. The online method restarts the instance as part of the upgrade process, while the offline method requires the provided EC2 instance be stopped and then started.
**Important**
If your instances connect to AWS Systems Manager using VPC endpoints, this runbook will fail unless used in the us-east-1 Region. This runbook will also fail on a domain controller. To update AWS PV drivers on a domain controller, see [Upgrade a Domain Controller (AWS PV Upgrade)](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Upgrading_PV_drivers.html#aws-pv-upgrade-dc).
[Run this Automation (console)](https://console.aws.amazon.com/systems-manager/automation/execute/AWSSupport-UpgradeWindowsAWSDrivers)
**Document type**
Automation
**Owner**
Amazon
**Platforms**
Windows
**Parameters**
+ AllowOffline
Type: String
Valid values: true \$1 false
Default: false
Description: (Optional) Set it to true if you allow an offline drivers upgrade in case the online installation cannot be performed. Note: The offline method requires the provided EC2 instance be stopped and then started. Data stored in instance store volumes will be lost. The public IP address will change if you are not using an Elastic IP.
+ 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.
+ ForceUpgrade
Type: String
Valid values: true \$1 false
Default: false
Description: (Optional) Offline only - Set it to true if you allow the offline drivers upgrade to proceed even though your instance already has the latest drivers installed.
+ InstanceId
Type: String
Description: (Required) ID of your EC2 instance for Windows Server.
+ SubnetId
Type: String
Default: SelectedInstanceSubnet
Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the offline drivers upgrade. If no subnet ID is specified, Systems Manager Automation will create a new VPC.
**Important**
The subnet must be in the same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
**Required IAM permissions**
The `AutomationAssumeRole` parameter requires the following actions to use the runbook successfully.
The EC2 instance receiving the command must at minimum have an IAM role that includes permissions for **ssm:StartAutomationExecution** and **ssm:SendCommand** to run the automation and send the command to the instance, plus **ssm:GetAutomationExecution** to be able to read the automation output. You can attach the `AmazonSSMManagedInstanceCore` Amazon managed policy to your IAM role to provide these permissions. We recommend, however, using the Automation IAM role `AmazonSSMAutomationRole` for this purpose. For more information, see [Use IAM to configure roles for Automation](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-permissions.html).
If you are performing an offline upgrade, see the permissions required by [`AWSSupport-StartEC2RescueWorkflow`](automation-awssupport-startec2rescueworkflow.md).
**Document Steps**
1. `aws:assertAwsResourceProperty` - Verifies the input instance is Windows.
1. `aws:assertAwsResourceProperty` - Verifies the input instance is a managed instance. If so, the online upgrade starts, otherwise the offline upgrade is evaluated.
1. (Online upgrade) If the input instance is a managed instance:
1. `aws:createImage` - Creates an AMI backup.
1. `aws:createTags` - Tags the AMI backup.
1. `aws:runCommand` - Installs ENA network driver.
1. `aws:runCommand` - Installs NVMe driver.
1. `aws:runCommand` - Installs AWS PV driver.
1. (Offline upgrade) If the input instance is not a managed instance:
1. `aws:assertAwsResourceProperty` - Verifies the AllowOffline flag is set to `true`. If so, the offline upgrade starts, otherwise the automation ends.
1. `aws:changeInstanceState` - Stop the source instance.
1. `aws:changeInstanceState` - Force-stop the source instance.
1. `aws:createImage` - Create an AMI backup of the source instance.
1. `aws:createTags` - Tag the AMI backup of the source instance.
1. `aws:executeAwsApi` - Enable ENA for the instance
1. `aws:assertAwsResourceProperty` - Assert the ForceUpgrade flag.
1. Force offline upgrade) If **ForceUpgrade = true** then run `aws:executeAutomation` to invoke `AWSSupport-StartEC2RescueWorkflow` with the drivers force upgrade script. This installs the drivers regardless of the current version that is installed
1. (Offline upgrade) If **ForceUpgrade = false** then run `aws:executeAutomation` to invoke `AWSSupport-StartEC2RescueWorkflow` with the drivers upgrade script.
**Outputs**
preUpgradeBackup.ImageId
preOfflineUpgradeBackup.ImageId
`installAwsEnaNetworkDriverOnInstance.Output`
`installAWSNVMeOnInstance.Output`
`installAWSPVDriverOnInstance.Output`
upgradeDriversOffline.Output
forceUpgradeDriversOffline.Output