• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# Tutorials
The following tutorials help you to use AWS Systems Manager Automation to address common use cases. These tutorials demonstrate how to use your own runbooks, predefined runbooks provided by Automation, and other Systems Manager tools with other AWS services.
**Contents**
+ [Updating AMIs](automation-tutorial-update-ami.md)
+ [Update a Linux AMI](automation-tutorial-update-patch-linux-ami.md)
+ [Update a Linux AMI (AWS CLI)](automation-tutorial-update-ami.md#update-patch-linux-ami-cli)
+ [Update a Windows Server AMI](automation-tutorial-update-patch-windows-ami.md)
+ [Update a golden AMI using Automation, AWS Lambda, and Parameter Store](automation-tutorial-update-patch-golden-ami.md)
+ [Task 1: Create a parameter in Systems Manager Parameter Store](automation-tutorial-update-patch-golden-ami.md#create-parameter-ami)
+ [Task 2: Create an IAM role for AWS Lambda](automation-tutorial-update-patch-golden-ami.md#create-lambda-role)
+ [Task 3: Create an AWS Lambda function](automation-tutorial-update-patch-golden-ami.md#create-lambda-function)
+ [Task 4: Create a runbook and patch the AMI](automation-tutorial-update-patch-golden-ami.md#create-custom-ami-update-runbook)
+ [Updating AMIs using Automation and Jenkins](automation-tutorial-update-patch-ami-jenkins-integration.md)
+ [Updating AMIs for Auto Scaling groups](automation-tutorial-update-patch-windows-ami-autoscaling.md)
+ [Create the **PatchAMIAndUpdateASG** runbook](automation-tutorial-update-patch-windows-ami-autoscaling.md#create-autoscaling-update-runbook)
+ [Using AWS Support self-service runbooks](automation-tutorial-support-runbooks.md)
+ [Run the EC2Rescue tool on unreachable instances](automation-ec2rescue.md)
+ [How it works](automation-ec2rescue.md#automation-ec2rescue-how)
+ [Before you begin](automation-ec2rescue.md#automation-ec2rescue-begin)
+ [Granting `AWSSupport-EC2Rescue` permissions to perform actions on your instances](automation-ec2rescue.md#automation-ec2rescue-access)
+ [Granting permissions by using IAM policies](automation-ec2rescue.md#automation-ec2rescue-access-iam)
+ [Granting permissions by using an CloudFormation template](automation-ec2rescue.md#automation-ec2rescue-access-cfn)
+ [Running the Automation](automation-ec2rescue.md#automation-ec2rescue-executing)
+ [Reset passwords and SSH keys on EC2 instances](automation-ec2reset.md)
+ [How it works](automation-ec2reset.md#automation-ec2reset-how)
+ [Before you begin](automation-ec2reset.md#automation-ec2reset-begin)
+ [Granting AWSSupport-EC2Rescue permissions to perform actions on your instances](automation-ec2reset.md#automation-ec2reset-access)
+ [Granting permissions by using IAM policies](automation-ec2reset.md#automation-ec2reset-access-iam)
+ [Granting permissions by using an CloudFormation template](automation-ec2reset.md#automation-ec2reset-access-cfn)
+ [Running the Automation](automation-ec2reset.md#automation-ec2reset-executing)
+ [Passing data to Automation using input transformers](automation-tutorial-eventbridge-input-transformers.md)
# Updating AMIs
The following tutorials explain how to update Amazon Machine Image (AMIs) to include the latest patches.
**Topics**
+ [Update a Linux AMI](automation-tutorial-update-patch-linux-ami.md)
+ [Update a Linux AMI (AWS CLI)](#update-patch-linux-ami-cli)
+ [Update a Windows Server AMI](automation-tutorial-update-patch-windows-ami.md)
+ [Update a golden AMI using Automation, AWS Lambda, and Parameter Store](automation-tutorial-update-patch-golden-ami.md)
+ [Updating AMIs using Automation and Jenkins](automation-tutorial-update-patch-ami-jenkins-integration.md)
+ [Updating AMIs for Auto Scaling groups](automation-tutorial-update-patch-windows-ami-autoscaling.md)
# Update a Linux AMI
This Systems Manager Automation walkthrough shows you how to use the console or AWS CLI and the `AWS-UpdateLinuxAmi` runbook to update a Linux AMI with the latest patches of packages that you specify. Automation is a tool in AWS Systems Manager. The `AWS-UpdateLinuxAmi` runbook also automates the installation of additional site-specific packages and configurations. You can update a variety of Linux distributions using this walkthrough, including Ubuntu Server, Red Hat Enterprise Linux (RHEL), or Amazon Linux AMIs. For a full list of supported Linux versions, see [Patch Manager prerequisites](patch-manager-prerequisites.md).
The `AWS-UpdateLinuxAmi` runbook allows you to automate image maintenance tasks without having to author the runbook in JSON or YAML. You can use the `AWS-UpdateLinuxAmi` runbook to perform the following types of tasks.
+ Upgrade all distribution packages and Amazon software on an Amazon Linux, Red Hat Enterprise Linux, or Ubuntu Server Amazon Machine Image (AMI). This is the default runbook behavior.
+ Install AWS Systems Manager SSM Agent on an existing image to enable Systems Manager tools, such as running remote commands using AWS Systems Manager Run Command or software inventory collection using Inventory.
+ Install additional software packages.
**Before you begin**
Before you begin working with runbooks, configure roles and, optionally, EventBridge for Automation. For more information, see [Setting up Automation](automation-setup.md). This walkthrough also requires that you specify the name of an AWS Identity and Access Management (IAM) instance profile. For more information about creating an IAM instance profile, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).
The `AWS-UpdateLinuxAmi` runbook accepts the following input parameters.
****
| Parameter | Type | Description |
| --- | --- | --- |
| SourceAmiId | String | (Required) The source AMI ID. |
| IamInstanceProfileName | String | (Required) The name of the IAM instance profile role you created in [Configure instance permissions required for Systems Manager](setup-instance-permissions.md). The instance profile role gives Automation permission to perform actions on your instances, such as running commands or starting and stopping services. The runbook uses only the name of the instance profile role. If you specify the Amazon Resource Name (ARN), the automation fails. |
| AutomationAssumeRole | String | (Required) The name of the IAM service role you created in [Setting up Automation](automation-setup.md). The service role (also called an assume role) gives Automation permission to assume your IAM role and perform actions on your behalf. For example, the service role allows Automation to create a new AMI when running the `aws:createImage` action in a runbook. For this parameter, the complete ARN must be specified. |
| TargetAmiName | String | (Optional) The name of the new AMI after it is created. The default name is a system-generated string that includes the source AMI ID, and the creation time and date. |
| InstanceType | String | (Optional) The type of instance to launch as the workspace host. Instance types vary by region. The default type is t2.micro. |
| PreUpdateScript | String | (Optional) URL of a script to run before updates are applied. Default (\$1"none\$1") is to not run a script. |
| PostUpdateScript | String | (Optional) URL of a script to run after package updates are applied. Default (\$1"none\$1") is to not run a script. |
| IncludePackages | String | (Optional) Only update these named packages. By default (\$1"all\$1"), all available updates are applied. |
| ExcludePackages | String | (Optional) Names of packages to hold back from updates, under all conditions. By default (\$1"none\$1"), no package is excluded. |
**Automation Steps**
The `AWS-UpdateLinuxAmi` runbook includes the following automation actions, by default.
**Step 1: launchInstance (`aws:runInstances` action) **
This step launches an instance using Amazon Elastic Compute Cloud (Amazon EC2) userdata and an IAM instance profile role. Userdata installs the appropriate SSM Agent, based on the operating system. Installing SSM Agent enables you to utilize Systems Manager tools such as Run Command, State Manager, and Inventory.
**Step 2: updateOSSoftware (`aws:runCommand` action) **
This step runs the following commands on the launched instance:
+ Downloads an update script from Amazon S3.
+ Runs an optional pre-update script.
+ Updates distribution packages and Amazon software.
+ Runs an optional post-update script.
The execution log is stored in the /tmp folder for the user to view later.
If you want to upgrade a specific set of packages, you can supply the list using the `IncludePackages` parameter. When provided, the system attempts to update only these packages and their dependencies. No other updates are performed. By default, when no *include* packages are specified, the program updates all available packages.
If you want to exclude upgrading a specific set of packages, you can supply the list to the `ExcludePackages` parameter. If provided, these packages remain at their current version, independent of any other options specified. By default, when no *exclude* packages are specified, no packages are excluded.
**Step 3: stopInstance (`aws:changeInstanceState` action)**
This step stops the updated instance.
**Step 4: createImage (`aws:createImage` action) **
This step creates a new AMI with a descriptive name that links it to the source ID and creation time. For example: “AMI Generated by EC2 Automation on \$1\$1global:DATE\$1TIME\$1\$1 from \$1\$1SourceAmiId\$1\$1” where DATE\$1TIME and SourceID represent Automation variables.
**Step 5: terminateInstance (`aws:changeInstanceState` action) **
This step cleans up the automation by terminating the running instance.
**Output**
The automation returns the new AMI ID as output.
**Note**
By default, when Automation runs the `AWS-UpdateLinuxAmi` runbook, the system creates a temporary instance in the default VPC (172.30.0.0/16). If you deleted the default VPC, you will receive the following error:
`VPC not defined 400`
To solve this problem, you must make a copy of the `AWS-UpdateLinuxAmi` runbook and specify a subnet ID. For more information, see [VPC not defined 400](automation-troubleshooting.md#automation-trbl-common-vpc).
**To create a patched AMI using Automation (AWS Systems Manager)**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Automation**.
1. Choose **Execute automation**.
1. In the **Automation document** list, choose `AWS-UpdateLinuxAmi`.
1. In the **Document details** section, verify that **Document version** is set to **Default version at runtime**.
1. Choose **Next**.
1. In the **Execution mode** section, choose **Simple Execution**.
1. In the **Input parameters** section, enter the information you collected in the **Before you begin** section.
1. Choose **Execute**. The console displays the status of the Automation execution.
After the automation finishes, launch a test instance from the updated AMI to verify changes.
**Note**
If any step in the automation fails, information about the failure is listed on the **Automation Executions** page. The automation is designed to terminate the temporary instance after successfully completing all tasks. If a step fails, the system might not terminate the instance. So if a step fails, manually terminate the temporary instance.
## Update a Linux AMI (AWS CLI)
This AWS Systems Manager Automation walkthrough shows you how to use the AWS Command Line Interface (AWS CLI) and the Systems Manager `AWS-UpdateLinuxAmi` runbook to automatically patch a Linux Amazon Machine Image (AMI) with the latest versions of packages that you specify. Automation is a tool in AWS Systems Manager. The `AWS-UpdateLinuxAmi` runbook also automates the installation of additional site-specific packages and configurations. You can update a variety of Linux distributions using this walkthrough, including Ubuntu Server, Red Hat Enterprise Linux (RHEL), or Amazon Linux AMIs. For a full list of supported Linux versions, see [Patch Manager prerequisites](patch-manager-prerequisites.md).
The `AWS-UpdateLinuxAmi` runbook enables you to automate image-maintenance tasks without having to author the runbook in JSON or YAML. You can use the `AWS-UpdateLinuxAmi` runbook to perform the following types of tasks.
+ Upgrade all distribution packages and Amazon software on an Amazon Linux, RHEL, or Ubuntu Server Amazon Machine Image (AMI). This is the default runbook behavior.
+ Install AWS Systems Manager SSM Agent on an existing image to enable Systems Manager capabilities, such as running remote commands using AWS Systems Manager Run Command or software inventory collection using Inventory.
+ Install additional software packages.
**Before you begin**
Before you begin working with runbooks, configure roles and, optionally, EventBridge for Automation. For more information, see [Setting up Automation](automation-setup.md). This walkthrough also requires that you specify the name of an AWS Identity and Access Management (IAM) instance profile. For more information about creating an IAM instance profile, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).
The `AWS-UpdateLinuxAmi` runbook accepts the following input parameters.
****
| Parameter | Type | Description |
| --- | --- | --- |
| SourceAmiId | String | (Required) The source AMI ID. You can automatically reference the latest ID of an Amazon EC2 AMI for Linux by using a AWS Systems Manager Parameter Store *public* parameter. For more information, see [Query for the latest Amazon Linux AMI IDs using AWS Systems Manager Parameter Store](https://aws.amazon.com/blogs/compute/query-for-the-latest-amazon-linux-ami-ids-using-aws-systems-manager-parameter-store/). |
| IamInstanceProfileName | String | (Required) The name of the IAM instance profile role you created in [Configure instance permissions required for Systems Manager](setup-instance-permissions.md). The instance profile role gives Automation permission to perform actions on your instances, such as running commands or starting and stopping services. The runbook uses only the name of the instance profile role. |
| AutomationAssumeRole | String | (Required) The name of the IAM service role you created in [Setting up Automation](automation-setup.md). The service role (also called an assume role) gives Automation permission to assume your IAM role and perform actions on your behalf. For example, the service role allows Automation to create a new AMI when running the `aws:createImage` action in a runbook. For this parameter, the complete ARN must be specified. |
| TargetAmiName | String | (Optional) The name of the new AMI after it is created. The default name is a system-generated string that includes the source AMI ID, and the creation time and date. |
| InstanceType | String | (Optional) The type of instance to launch as the workspace host. Instance types vary by Region. The default type is t2.micro. |
| PreUpdateScript | String | (Optional) URL of a script to run before updates are applied. Default (\$1"none\$1") is to not run a script. |
| PostUpdateScript | String | (Optional) URL of a script to run after package updates are applied. Default (\$1"none\$1") is to not run a script. |
| IncludePackages | String | (Optional) Only update these named packages. By default (\$1"all\$1"), all available updates are applied. |
| ExcludePackages | String | (Optional) Names of packages to hold back from updates, under all conditions. By default (\$1"none\$1"), no package is excluded. |
**Automation Steps**
The `AWS-UpdateLinuxAmi` runbook includes the following steps, by default.
**Step 1: launchInstance (`aws:runInstances` action) **
This step launches an instance using Amazon Elastic Compute Cloud (Amazon EC2) user data and an IAM instance profile role. User data installs the appropriate SSM Agent, based on the operating system. Installing SSM Agent enables you to utilize Systems Manager tools such as Run Command, State Manager, and Inventory.
**Step 2: updateOSSoftware (`aws:runCommand` action) **
This step runs the following commands on the launched instance:
+ Downloads an update script from Amazon Simple Storage Service (Amazon S3).
+ Runs an optional pre-update script.
+ Updates distribution packages and Amazon software.
+ Runs an optional post-update script.
The execution log is stored in the /tmp folder for the user to view later.
If you want to upgrade a specific set of packages, you can supply the list using the `IncludePackages` parameter. When provided, the system attempts to update only these packages and their dependencies. No other updates are performed. By default, when no *include* packages are specified, the program updates all available packages.
If you want to exclude upgrading a specific set of packages, you can supply the list to the `ExcludePackages` parameter. If provided, these packages remain at their current version, independent of any other options specified. By default, when no *exclude* packages are specified, no packages are excluded.
**Step 3: stopInstance (`aws:changeInstanceState` action)**
This step stops the updated instance.
**Step 4: createImage (`aws:createImage` action) **
This step creates a new AMI with a descriptive name that links it to the source ID and creation time. For example: “AMI Generated by EC2 Automation on \$1\$1global:DATE\$1TIME\$1\$1 from \$1\$1SourceAmiId\$1\$1” where DATE\$1TIME and SourceID represent Automation variables.
**Step 5: terminateInstance (`aws:changeInstanceState` action) **
This step cleans up the automation by terminating the running instance.
**Output**
The automation returns the new AMI ID as output.
**Note**
By default, when Automation runs the `AWS-UpdateLinuxAmi` runbook, the system creates a temporary instance in the default VPC (172.30.0.0/16). If you deleted the default VPC, you will receive the following error:
`VPC not defined 400`
To solve this problem, you must make a copy of the `AWS-UpdateLinuxAmi` runbook and specify a subnet ID. For more information, see [VPC not defined 400](automation-troubleshooting.md#automation-trbl-common-vpc).
**To create a patched AMI using Automation**
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to run the `AWS-UpdateLinuxAmi` runbook. Replace each *example resource placeholder* with your own information.
```
aws ssm start-automation-execution \
--document-name "AWS-UpdateLinuxAmi" \
--parameters \
SourceAmiId=AMI ID, \
IamInstanceProfileName=IAM instance profile, \
AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'
```
The command returns an execution ID. Copy this ID to the clipboard. You will use this ID to view the status of the automation.
```
{
"AutomationExecutionId": "automation execution ID"
}
```
1. To view the automation using the AWS CLI, run the following command:
```
aws ssm describe-automation-executions
```
1. To view details about the automation progress, run the following command. Replace *automation execution ID* with your own information.
```
aws ssm get-automation-execution --automation-execution-id automation execution ID
```
The update process can take 30 minutes or more to complete.
**Note**
You can also monitor the status of the automation in the console. In the list, choose the automation you just ran and then choose the **Steps** tab. This tab shows you the status of the automation actions.
After the automation finishes, launch a test instance from the updated AMI to verify changes.
**Note**
If any step in the automation fails, information about the failure is listed on the **Automation Executions** page. The automation is designed to terminate the temporary instance after successfully completing all tasks. If a step fails, the system might not terminate the instance. So if a step fails, manually terminate the temporary instance.
# Update a Windows Server AMI
The `AWS-UpdateWindowsAmi` runbook enables you to automate image maintenance tasks on your Amazon Windows Amazon Machine Image (AMI) without having to author the runbook in JSON or YAML. This runbook is supported for Windows Server 2008 R2 or later. You can use the `AWS-UpdateWindowsAmi` runbook to perform the following types of tasks.
+ Install all Windows updates and upgrade Amazon software (default behavior).
+ Install specific Windows updates and upgrade Amazon software.
+ Customize an AMI using your scripts.
**Before you begin**
Before you begin working with runbooks, [configure roles for Automation](automation-setup-iam.md) to add an `iam:PassRole` policy that references the ARN of the instance profile you want to grant access to. Optionally, configure Amazon EventBridge for Automation, a tool in AWS Systems Manager. For more information, see [Setting up Automation](automation-setup.md). This walkthrough also requires that you specify the name of an AWS Identity and Access Management (IAM) instance profile. For more information about creating an IAM instance profile, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).
**Note**
Updates to AWS Systems Manager SSM Agent are typically rolled out to different regions at different times. When you customize or update an AMI, use only source AMIs published for the region that you are working in. This will ensure that you are working with the latest SSM Agent released for that region and avoid compatibility issues.
The `AWS-UpdateWindowsAmi` runbook accepts the following input parameters.
****
| Parameter | Type | Description |
| --- | --- | --- |
| SourceAmiId | String | (Required) The source AMI ID. You can automatically reference the latest Windows Server AMI ID by using a Systems Manager Parameter Store *public* parameter. For more information, see [Query for the latest Windows AMI IDs using AWS Systems Manager Parameter Store](https://aws.amazon.com/blogs/mt/query-for-the-latest-windows-ami-using-systems-manager-parameter-store/). |
| SubnetId | String | (Optional) The subnet you want to launch the temporary instance into. You must specify a value for this parameter if you've deleted your default VPC. |
| IamInstanceProfileName | String | (Required) The name of the IAM instance profile role you created in [Configure instance permissions required for Systems Manager](setup-instance-permissions.md). The instance profile role gives Automation permission to perform actions on your instances, such as running commands or starting and stopping services. The runbook uses only the name of the instance profile role. |
| AutomationAssumeRole | String | (Required) The name of the IAM service role you created in [Setting up Automation](automation-setup.md). The service role (also called an assume role) gives Automation permission to assume your IAM role and perform actions on your behalf. For example, the service role allows Automation to create a new AMI when running the `aws:createImage` action in a runbook. For this parameter, the complete ARN must be specified. |
| TargetAmiName | String | (Optional) The name of the new AMI after it is created. The default name is a system-generated string that includes the source AMI ID, and the creation time and date. |
| InstanceType | String | (Optional) The type of instance to launch as the workspace host. Instance types vary by region. The default type is t2.medium. |
| PreUpdateScript | String | (Optional) A script to run before updating the AMI. Enter a script in the runbook or at runtime as a parameter. |
| PostUpdateScript | String | (Optional) A script to run after updating the AMI. Enter a script in the runbook or at runtime as a parameter. |
| IncludeKbs | String | (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. |
| ExcludeKbs | String | (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. |
| Categories | String | (Optional)Specify one or more update categories. You can filter categories using comma-separated values. Options: Critical Update, Security Update, Definition Update, Update Rollup, Service Pack, Tool, Update, or Driver. Valid formats include a single entry, for example: Critical Update. Or, you can specify a comma separated list: Critical Update,Security Update,Definition Update. |
| SeverityLevels | String | (Optional) Specify one or more MSRC severity levels associated with an update. You can filter severity levels using comma-separated 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. |
**Automation Steps**
The `AWS-UpdateWindowsAmi` runbook includes the following steps, by default.
**Step 1: launchInstance (`aws:runInstances` action)**
This step launches an instance with an IAM instance profile role from the specified `SourceAmiID`.
**Step 2: runPreUpdateScript (`aws:runCommand` action)**
This step enables you to specify a script as a string that runs before updates are installed.
**Step 3: updateEC2Config (`aws:runCommand` action)**
This step uses the `AWS-InstallPowerShellModule` runbook to download an AWS public PowerShell module. Systems Manager verifies the integrity of the module by using an SHA-256 hash. Systems Manager then checks the operating system to determine whether to update EC2Config or EC2Launch. EC2Config runs on Windows Server 2008 R2 through Windows Server 2012 R2. EC2Launch runs on Windows Server 2016.
**Step 4: updateSSMAgent (`aws:runCommand` action)**
This step updates SSM Agent by using the `AWS-UpdateSSMAgent` runbook.
**Step 5: updateAWSPVDriver (`aws:runCommand` action)**
This step updates AWS PV drivers by using the `AWS-ConfigureAWSPackage` runbook.
**Step 6: updateAwsEnaNetworkDriver (`aws:runCommand` action)**
This step updates AWS ENA Network drivers by using the `AWS-ConfigureAWSPackage` runbook.
**Step 7: installWindowsUpdates (`aws:runCommand` action) **
This step installs Windows updates by using the `AWS-InstallWindowsUpdates` runbook. By default, Systems Manager searches for and installs all missing updates. You can change the default behavior by specifying one of the following parameters: `IncludeKbs`, `ExcludeKbs`, `Categories`, or `SeverityLevels`.
**Step 8: runPostUpdateScript (`aws:runCommand` action)**
This step enables you to specify a script as a string that runs after the updates have been installed.
**Step 9: runSysprepGeneralize (`aws:runCommand` action) **
This step uses the `AWS-InstallPowerShellModule` runbook to download an AWS public PowerShell module. Systems Manager verifies the integrity of the module by using an SHA-256 hash. Systems Manager then runs sysprep using AWS-supported methods for either EC2Launch (Windows Server 2016) or EC2Config (Windows Server 2008 R2 through 2012 R2).
**Step 10: stopInstance (`aws:changeInstanceState` action) **
This step stops the updated instance.
**Step 11: createImage (`aws:createImage` action) **
This step creates a new AMI with a descriptive name that links it to the source ID and creation time. For example: “AMI Generated by EC2 Automation on \$1\$1global:DATE\$1TIME\$1\$1 from \$1\$1SourceAmiId\$1\$1” where DATE\$1TIME and SourceID represent Automation variables.
**Step 12: TerminateInstance (`aws:changeInstanceState` action) **
This step cleans up the automation by terminating the running instance.
**Output**
This section enables you to designate the outputs of various steps or values of any parameter as the Automation output. By default, the output is the ID of the updated Windows AMI created by the automation.
**Note**
By default, when Automation runs the `AWS-UpdateWindowsAmi` runbook and creates a temporary instance, the system uses the default VPC (172.30.0.0/16). If you deleted the default VPC, you will receive the following error:
VPC not defined 400
To solve this problem, you must make a copy of the `AWS-UpdateWindowsAmi` runbook and specify a subnet ID. For more information, see [VPC not defined 400](automation-troubleshooting.md#automation-trbl-common-vpc).
**To create a patched Windows AMI by using Automation**
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to run the `AWS-UpdateWindowsAmi` runbook. Replace each *example resource placeholder* with your own information. The example command below uses a recent Amazon EC2 AMI to minimize the number of patches that need to be applied. If you run this command more than once, you must specify a unique value for `targetAMIname`. AMI names must be unique.
```
aws ssm start-automation-execution \
--document-name="AWS-UpdateWindowsAmi" \
--parameters SourceAmiId='AMI ID',IamInstanceProfileName='IAM instance profile',AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'
```
The command returns an execution ID. Copy this ID to the clipboard. You will use this ID to view the status of the automation.
```
{
"AutomationExecutionId": "automation execution ID"
}
```
1. To view the automation using the AWS CLI, run the following command:
```
aws ssm describe-automation-executions
```
1. To view details about the automation progress, run the following command.
```
aws ssm get-automation-execution
--automation-execution-id automation execution ID
```
**Note**
Depending on the number of patches applied, the Windows patching process run in this sample automation can take 30 minutes or more to complete.
# Update a golden AMI using Automation, AWS Lambda, and Parameter Store
The following example uses the model where an organization maintains and periodically patches their own, proprietary AMIs rather than building from Amazon Elastic Compute Cloud (Amazon EC2) AMIs.
The following procedure shows how to automatically apply operating system (OS) patches to an AMI that is already considered to be the most up-to-date or *latest* AMI. In the example, the default value of the parameter `SourceAmiId` is defined by a AWS Systems Manager Parameter Store parameter called `latestAmi`. The value of `latestAmi` is updated by an AWS Lambda function invoked at the end of the automation. As a result of this Automation process, the time and effort spent patching AMIs is minimized because patching is always applied to the most up-to-date AMI. Parameter Store and Automation are tools of AWS Systems Manager.
**Before you begin**
Configure Automation roles and, optionally, Amazon EventBridge for Automation. For more information, see [Setting up Automation](automation-setup.md).
**Topics**
+ [Task 1: Create a parameter in Systems Manager Parameter Store](#create-parameter-ami)
+ [Task 2: Create an IAM role for AWS Lambda](#create-lambda-role)
+ [Task 3: Create an AWS Lambda function](#create-lambda-function)
+ [Task 4: Create a runbook and patch the AMI](#create-custom-ami-update-runbook)
## Task 1: Create a parameter in Systems Manager Parameter Store
Create a string parameter in Parameter Store that uses the following information:
+ **Name**: `latestAmi`.
+ **Value**: An AMI ID. For example:` ami-188d6e0e`.
For information about how to create a Parameter Store string parameter, see [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md).
## Task 2: Create an IAM role for AWS Lambda
Use the following procedure to create an IAM service role for AWS Lambda. These policies give Lambda permission to update the value of the `latestAmi` parameter using a Lambda function and Systems Manager.
**To create an IAM service role for Lambda**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create policy**.
1. Choose the **JSON** tab.
1. Replace the default contents with the following policy. Replace each *example resource placeholder* with your own information.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:us-east-1:111122223333:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:/aws/lambda/function name:*"
]
}
]
}
```
------
1. Choose **Next: Tags**.
1. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy.
1. Choose **Next: Review**.
1. On the **Review policy** page, for **Name**, enter a name for the inline policy, such as **amiLambda**.
1. Choose **Create policy**.
1. Repeat steps 2 and 3.
1. Paste the following policy. Replace each *example resource placeholder* with your own information.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:PutParameter",
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/latestAmi"
},
{
"Effect": "Allow",
"Action": "ssm:DescribeParameters",
"Resource": "*"
}
]
}
```
------
1. Choose **Next: Tags**.
1. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy.
1. Choose **Next: Review**.
1. On the **Review policy** page, for **Name**, enter a name for the inline policy, such as **amiParameter**.
1. Choose **Create policy**.
1. In the navigation pane, choose **Roles**, and then choose **Create role**.
1. Immediately under **Use case**, choose **Lambda**, and then choose **Next**.
1. On the **Add permissions** page, use the **Search** field to locate the two policies you created earlier.
1. Select the check box next to the policies, and then choose **Next**.
1. For **Role name**, enter a name for your new role, such as **lambda-ssm-role** or another name that you prefer.
**Note**
Because various entities might reference the role, you cannot change the name of the role after it has been created.
1. (Optional) Add one or more tag key-value pairs to organize, track, or control access for this role, and then choose **Create role**.
## Task 3: Create an AWS Lambda function
Use the following procedure to create a Lambda function that automatically updates the value of the `latestAmi` parameter.
**To create a Lambda function**
1. Sign in to the AWS Management Console and open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).
1. Choose **Create function**.
1. On the **Create function** page, choose **Author from scratch**.
1. For **Function name**, enter **Automation-UpdateSsmParam**.
1. For **Runtime**, choose **Python 3.11**.
1. For **Architecture**, select the type of computer processor for Lambda to use to run the function, **x86\$164** or **arm64**,
1. In the **Permissions** section, expand **Change default execution role**.
1. Choose **Use an existing role**, and then choose the service role for Lambda that you created in Task 2.
1. Choose **Create function**.
1. In the **Code source** area, on the **lambda\$1function** tab, delete the pre-populated code in the field, and then paste the following code sample.
```
from __future__ import print_function
import json
import boto3
print('Loading function')
#Updates an SSM parameter
#Expects parameterName, parameterValue
def lambda_handler(event, context):
print("Received event: " + json.dumps(event, indent=2))
# get SSM client
client = boto3.client('ssm')
#confirm parameter exists before updating it
response = client.describe_parameters(
Filters=[
{
'Key': 'Name',
'Values': [ event['parameterName'] ]
},
]
)
if not response['Parameters']:
print('No such parameter')
return 'SSM parameter not found.'
#if parameter has a Description field, update it PLUS the Value
if 'Description' in response['Parameters'][0]:
description = response['Parameters'][0]['Description']
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Description=description,
Type='String',
Overwrite=True
)
#otherwise just update Value
else:
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Type='String',
Overwrite=True
)
responseString = 'Updated parameter %s with value %s.' % (event['parameterName'], event['parameterValue'])
return responseString
```
1. Choose **File, Save**.
1. To test the Lambda function, from the **Test** menu, choose **Configure test event**.
1. For **Event name**, enter a name for the test event, such as **MyTestEvent**.
1. Replace the existing text with the following JSON. Replace *AMI ID* with your own information to set your `latestAmi` parameter value.
```
{
"parameterName":"latestAmi",
"parameterValue":"AMI ID"
}
```
1. Choose **Save**.
1. Choose **Test** to test the function. On the **Execution result** tab, the status should be reported as **Succeeded**, along with other details about the update.
## Task 4: Create a runbook and patch the AMI
Use the following procedure to create and run a runbook that patches the AMI you specified for the **latestAmi** parameter. After the automation completes, the value of **latestAmi** is updated with the ID of the newly-patched AMI. Subsequent automations use the AMI created by the previous execution.
**To create and run the runbook**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Documents**.
1. For **Create document**, choose **Automation**.
1. For **Name**, enter **UpdateMyLatestWindowsAmi**.
1. Choose the **Editor** tab, and then choose **Edit**.
1. Choose **OK** when prompted.
1. In the **Document editor** field, replace the default content with the following YAML sample runbook content.
```
---
description: Systems Manager Automation Demo - Patch AMI and Update ASG
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.'
default: ''
SourceAMI:
type: String
description: The ID of the AMI you want to patch.
default: '{{ ssm:latestAmi }}'
SubnetId:
type: String
description: The ID of the subnet where the instance from the SourceAMI parameter is launched.
SecurityGroupIds:
type: StringList
description: The IDs of the security groups to associate with the instance that's launched from the SourceAMI parameter.
NewAMI:
type: String
description: The name of of newly patched AMI.
default: 'patchedAMI-{{global:DATE_TIME}}'
InstanceProfile:
type: String
description: The name of the IAM instance profile you want the source instance to use.
SnapshotId:
type: String
description: (Optional) The snapshot ID to use to retrieve a patch baseline snapshot.
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: (Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: startInstances
action: 'aws:runInstances'
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
ImageId: '{{ SourceAMI }}'
InstanceType: m5.large
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: '{{ InstanceProfile }}'
SubnetId: '{{ SubnetId }}'
SecurityGroupIds: '{{ SecurityGroupIds }}'
- name: verifyInstanceManaged
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ startInstances.InstanceIds }}'
PropertySelector: '$.InstanceInformationList[0].PingStatus'
DesiredValues:
- Online
onFailure: 'step:terminateInstance'
- name: installPatches
action: 'aws:runCommand'
timeoutSeconds: 7200
onFailure: Abort
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
InstanceIds:
- '{{ startInstances.InstanceIds }}'
- name: stopInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: stopped
- name: createImage
action: 'aws:createImage'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceId: '{{ startInstances.InstanceIds }}'
ImageName: '{{ NewAMI }}'
NoReboot: false
ImageDescription: Patched AMI created by Automation
- name: terminateInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: terminated
- name: updateSsmParam
action: aws:invokeLambdaFunction
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
FunctionName: Automation-UpdateSsmParam
Payload: '{"parameterName":"latestAmi", "parameterValue":"{{createImage.ImageId}}"}'
outputs:
- createImage.ImageId
```
1. Choose **Create automation**.
1. In the navigation pane, choose **Automation**, and then choose **Execute automation**.
1. In the **Choose document** page, choose the **Owned by me** tab.
1. Search for the **UpdateMyLatestWindowsAmi** runbook, and select the button in the **UpdateMyLatestWindowsAmi** card.
1. Choose **Next**.
1. Choose **Simple execution**.
1. Specify values for the input parameters.
1. Choose **Execute**.
1. After the automation completes, choose **Parameter Store** in the navigation pane and confirm that the new value for `latestAmi` matches the value returned by the automation. You can also verify the new AMI ID matches the Automation output in the **AMIs** section of the Amazon EC2 console.
# Updating AMIs using Automation and Jenkins
If your organization uses Jenkins software in a CI/CD pipeline, you can add Automation as a post-build step to pre-install application releases into Amazon Machine Images (AMIs). Automation is a tool in AWS Systems Manager. You can also use the Jenkins scheduling feature to call Automation and create your own operating system (OS) patching cadence.
The example below shows how to invoke Automation from a Jenkins server that is running either on-premises or in Amazon Elastic Compute Cloud (Amazon EC2). For authentication, the Jenkins server uses AWS credentials based on an IAM policy that you create in the example and attach to your instance profile.
**Note**
Be sure to follow Jenkins security best practices when configuring your instance.
**Before you begin**
Complete the following tasks before you configure Automation with Jenkins:
+ Complete the [Update a golden AMI using Automation, AWS Lambda, and Parameter Store](automation-tutorial-update-patch-golden-ami.md) example. The following example uses the **UpdateMyLatestWindowsAmi** runbook created in that example.
+ Configure IAM roles for Automation. Systems Manager requires an instance profile role and a service role ARN to process automations. For more information, see [Setting up Automation](automation-setup.md).
**To create an IAM policy for the Jenkins server**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create policy**.
1. Choose the **JSON** tab.
1. Replace each *example resource placeholder* with your own information.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartAutomationExecution",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/UpdateMyLatestWindowsAmi",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
}
]
}
```
------
1. Choose **Review policy**.
1. On the **Review policy** page, for **Name**, enter a name for the inline policy, such as **JenkinsPolicy**.
1. Choose **Create policy**.
1. In the navigation pane, choose **Roles**.
1. Choose the instance profile that's attached to your Jenkins server.
1. In the **Permissions** tab, select **Add permissions** and choose **Attach policies**.
1. In the **Other permissions policies** section, enter the name of policy you created in the previous steps. For example, **JenkinsPolicy**.
1. Select the check box next to your policy, and choose **Attach policies**.
Use the following procedure to configure the AWS CLI on your Jenkins server.
**To configure the Jenkins server for Automation**
1. Connect to your Jenkins server on port 8080 using your preferred browser to access the management interface.
1. Enter the password found in `/var/lib/jenkins/secrets/initialAdminPassword`. To display your password, run the following command.
```
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
```
1. The Jenkins installation script directs you to the **Customize Jenkins** page. Select **Install suggested plugins**.
1. Once the installation is complete, choose **Administrator Credentials**, select **Save Credentials**, and then select **Start Using Jenkins**.
1. In the left navigation pane, choose **Manage Jenkins**, and then choose **Manage Plugins**.
1. Choose the **Available** tab, and then enter **Amazon EC2 plugin**.
1. Select the check box for **Amazon EC2 plugin**, and then select **Install without restart**.
1. When the installation completes, select **Go back to the top page**.
1. Choose **Manage Jenkins**, and then choose **Manage nodes and clouds**.
1. In the **Configure Clouds** section, select **Add a new cloud**, and then choose **Amazon EC2**.
1. Enter your information in the remaining fields. Make sure you select the **Use EC2 instance profile to obtain credentials** option.
Use the following procedure to configure your Jenkins project to invoke Automation.
**To configure your Jenkins server to invoke Automation**
1. Open the Jenkins console in a web browser.
1. Choose the project that you want to configure with Automation, and then choose **Configure**.
1. On the **Build** tab, choose **Add Build Step**.
1. Choose **Execute shell** or **Execute Windows batch command** (depending on your operating system).
1. In the **Command** field, run an AWS CLI command like the following. Replace each *example resource placeholder* with your own information.
```
aws ssm start-automation-execution \
--document-name runbook name \
--region AWS Region of your source AMI \
--parameters runbook parameters
```
The following example command uses the **UpdateMyLatestWindowsAmi** runbook and the Systems Manager Parameter `latestAmi` created in [Update a golden AMI using Automation, AWS Lambda, and Parameter Store](automation-tutorial-update-patch-golden-ami.md).
```
aws ssm start-automation-execution \
--document-name UpdateMyLatestWindowsAmi \
--parameters \
"sourceAMIid='{{ssm:latestAmi}}'"
--region region
```
In Jenkins, the command looks like the example in the following screenshot.
![\[A sample command in Jenkins software.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/sysman-ami-jenkins2.png)
1. In the Jenkins project, choose **Build Now**. Jenkins returns output similar to the following example.
![\[Sample command output in Jenkins software.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/sysman-ami-jenkins.png)
# Updating AMIs for Auto Scaling groups
The following example updates an Auto Scaling group with a newly patched AMI. This approach ensures that new images are automatically made available to different computing environments that use Auto Scaling groups.
The final step of the automation in this example uses a Python function to create a new launch template that uses the newly patched AMI. Then the Auto Scaling group is updated to use the new launch template. In this type of Auto Scaling scenario, users could terminate existing instances in the Auto Scaling group to force a new instance to launch that uses the new image. Or, users could wait and allow scale-in or scale-out events to naturally launch newer instances.
**Before you begin**
Complete the following tasks before you begin this example.
+ Configure IAM roles for Automation, a tool in AWS Systems Manager. Systems Manager requires an instance profile role and a service role ARN to process automations. For more information, see [Setting up Automation](automation-setup.md).
## Create the **PatchAMIAndUpdateASG** runbook
Use the following procedure to create the **PatchAMIAndUpdateASG** runbook that patches the AMI you specify for the **SourceAMI** parameter. The runbook also updates an Auto Scaling group to use the latest, patched AMI.
**To create and run the runbook**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Documents**.
1. In the **Create document** dropdown, choose **Automation**.
1. In the **Name** field, enter **PatchAMIAndUpdateASG**.
1. Choose the **Editor** tab, and choose the **Edit**.
1. Choose **OK** when prompted, and delete the content in the **Document editor** field.
1. In the **Document editor** field, paste the following YAML sample runbook content.
```
---
description: Systems Manager Automation Demo - Patch AMI and Update ASG
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.'
default: ''
SourceAMI:
type: String
description: '(Required) The ID of the AMI you want to patch.'
SubnetId:
type: String
description: '(Required) The ID of the subnet where the instance from the SourceAMI parameter is launched.'
SecurityGroupIds:
type: StringList
description: '(Required) The IDs of the security groups to associate with the instance launched from the SourceAMI parameter.'
NewAMI:
type: String
description: '(Optional) The name of of newly patched AMI.'
default: 'patchedAMI-{{global:DATE_TIME}}'
TargetASG:
type: String
description: '(Required) The name of the Auto Scaling group you want to update.'
InstanceProfile:
type: String
description: '(Required) The name of the IAM instance profile you want the source instance to use.'
SnapshotId:
type: String
description: (Optional) The snapshot ID to use to retrieve a patch baseline snapshot.
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: (Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: startInstances
action: 'aws:runInstances'
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
ImageId: '{{ SourceAMI }}'
InstanceType: m5.large
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: '{{ InstanceProfile }}'
SubnetId: '{{ SubnetId }}'
SecurityGroupIds: '{{ SecurityGroupIds }}'
- name: verifyInstanceManaged
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ startInstances.InstanceIds }}'
PropertySelector: '$.InstanceInformationList[0].PingStatus'
DesiredValues:
- Online
onFailure: 'step:terminateInstance'
- name: installPatches
action: 'aws:runCommand'
timeoutSeconds: 7200
onFailure: Abort
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
InstanceIds:
- '{{ startInstances.InstanceIds }}'
- name: stopInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: stopped
- name: createImage
action: 'aws:createImage'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceId: '{{ startInstances.InstanceIds }}'
ImageName: '{{ NewAMI }}'
NoReboot: false
ImageDescription: Patched AMI created by Automation
- name: terminateInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: terminated
- name: updateASG
action: 'aws:executeScript'
timeoutSeconds: 300
maxAttempts: 1
onFailure: Abort
inputs:
Runtime: python3.11
Handler: update_asg
InputPayload:
TargetASG: '{{TargetASG}}'
NewAMI: '{{createImage.ImageId}}'
Script: |-
from __future__ import print_function
import datetime
import json
import time
import boto3
# create auto scaling and ec2 client
asg = boto3.client('autoscaling')
ec2 = boto3.client('ec2')
def update_asg(event, context):
print("Received event: " + json.dumps(event, indent=2))
target_asg = event['TargetASG']
new_ami = event['NewAMI']
# get object for the ASG we're going to update, filter by name of target ASG
asg_query = asg.describe_auto_scaling_groups(AutoScalingGroupNames=[target_asg])
if 'AutoScalingGroups' not in asg_query or not asg_query['AutoScalingGroups']:
return 'No ASG found matching the value you specified.'
# gets details of an instance from the ASG that we'll use to model the new launch template after
source_instance_id = asg_query.get('AutoScalingGroups')[0]['Instances'][0]['InstanceId']
instance_properties = ec2.describe_instances(
InstanceIds=[source_instance_id]
)
source_instance = instance_properties['Reservations'][0]['Instances'][0]
# create list of security group IDs
security_groups = []
for group in source_instance['SecurityGroups']:
security_groups.append(group['GroupId'])
# create a list of dictionary objects for block device mappings
mappings = []
for block in source_instance['BlockDeviceMappings']:
volume_query = ec2.describe_volumes(
VolumeIds=[block['Ebs']['VolumeId']]
)
volume_details = volume_query['Volumes']
device_name = block['DeviceName']
volume_size = volume_details[0]['Size']
volume_type = volume_details[0]['VolumeType']
device = {'DeviceName': device_name, 'Ebs': {'VolumeSize': volume_size, 'VolumeType': volume_type}}
mappings.append(device)
# create new launch template using details returned from instance in the ASG and specify the newly patched AMI
time_stamp = time.time()
time_stamp_string = datetime.datetime.fromtimestamp(time_stamp).strftime('%m-%d-%Y_%H-%M-%S')
new_template_name = f'{new_ami}_{time_stamp_string}'
try:
ec2.create_launch_template(
LaunchTemplateName=new_template_name,
LaunchTemplateData={
'BlockDeviceMappings': mappings,
'ImageId': new_ami,
'InstanceType': source_instance['InstanceType'],
'IamInstanceProfile': {
'Arn': source_instance['IamInstanceProfile']['Arn']
},
'KeyName': source_instance['KeyName'],
'SecurityGroupIds': security_groups
}
)
except Exception as e:
return f'Exception caught: {str(e)}'
else:
# update ASG to use new launch template
asg.update_auto_scaling_group(
AutoScalingGroupName=target_asg,
LaunchTemplate={
'LaunchTemplateName': new_template_name
}
)
return f'Updated ASG {target_asg} with new launch template {new_template_name} which uses AMI {new_ami}.'
outputs:
- createImage.ImageId
```
1. Choose **Create automation**.
1. In the navigation pane, choose **Automation**, and then choose **Execute automation**.
1. In the **Choose document** page, choose the **Owned by me** tab.
1. Search for the **PatchAMIAndUpdateASG** runbook, and select the button in the **PatchAMIAndUpdateASG** card.
1. Choose **Next**.
1. Choose **Simple execution**.
1. Specify values for the input parameters. Be sure the `SubnetId` and `SecurityGroupIds` you specify allow access to the public Systems Manager endpoints, or your interface endpoints for Systems Manager.
1. Choose **Execute**.
1. After automation completes, in the Amazon EC2 console, choose **Auto Scaling**, and then choose **Launch Templates**. Verify that you see the new launch template, and that it uses the new AMI.
1. Choose **Auto Scaling**, and then choose **Auto Scaling Groups**. Verify that the Auto Scaling group uses the new launch template.
1. Terminate one or more instances in your Auto Scaling group. Replacement instances will be launched using the new AMI.
# Using AWS Support self-service runbooks
This section describes how to use some of the self-service automations created by the AWS Support team. These automations help you manage your AWS resources.
**Support Automation Workflows**
Support Automation Workflows (SAW) are automation runbooks written and maintained by the AWS Support team. These runbooks help you troubleshoot common issues with your AWS resources, proactively monitor and identify network issues, collect and analyze logs, and more.
SAW runbooks use the **`AWSSupport`** prefix. For example, [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-activatewindowswithamazonlicense.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-activatewindowswithamazonlicense.html).
Additionally, customers with Business Support\$1 and higher AWS Support plans also have access to runbooks that use the **`AWSPremiumSupport`** prefix. For example, [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awspremiumsupport-troubleshootEC2diskusage.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awspremiumsupport-troubleshootEC2diskusage.html).
To learn more about AWS Support, see [Getting started with AWS Support](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html).
**Topics**
+ [Run the EC2Rescue tool on unreachable instances](automation-ec2rescue.md)
+ [Reset passwords and SSH keys on EC2 instances](automation-ec2reset.md)
# Run the EC2Rescue tool on unreachable instances
EC2Rescue can help you diagnose and troubleshoot problems on Amazon Elastic Compute Cloud (Amazon EC2) instances for Linux and Windows Server. You can run the tool manually, as described in [Using EC2Rescue for Linux Server](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Linux-Server-EC2Rescue.html) and [Using EC2Rescue for Windows Server](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Windows-Server-EC2Rescue.html). Or, you can run the tool automatically by using Systems Manager Automation and the **`AWSSupport-ExecuteEC2Rescue`** runbook. Automation is a tool in AWS Systems Manager. The **`AWSSupport-ExecuteEC2Rescue`** runbook is designed to perform a combination of Systems Manager actions, CloudFormation actions, and Lambda functions that automate the steps normally required to use EC2Rescue.
You can use the **`AWSSupport-ExecuteEC2Rescue`** runbook to troubleshoot and potentially remediate different types of operating system (OS) issues. Instances with encypted root volumes are not supported. See the following topics for a complete list:
**Windows**: See *Rescue Action* in [Using EC2Rescue for Windows Server with the Command Line](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-cli.html#ec2rw-rescue).
**Linux** and **macOS**: Some EC2Rescue for Linux modules detect and attempt to remediate issues. For more information, see the [https://github.com/awslabs/aws-ec2rescue-linux/tree/master/docs](https://github.com/awslabs/aws-ec2rescue-linux/tree/master/docs) documentation for each module on GitHub.
## How it works
Troubleshooting an instance with Automation and the **`AWSSupport-ExecuteEC2Rescue`** runbook works as follows:
+ You specify the ID of the unreachable instance and start the runbook.
+ The system creates a temporary VPC, and then runs a series of Lambda functions to configure the VPC.
+ The system identifies a subnet for your temporary VPC in the same Availability Zone as your original instance.
+ The system launches a temporary, SSM-enabled helper instance.
+ The system stops your original instance, and creates a backup. It then attaches the original root volume to the helper instance.
+ The system uses Run Command to run EC2Rescue on the helper instance. EC2Rescue identifies and attempts to fix issues on the attached, original root volume. When finished, EC2Rescue reattaches the root volume back to the original instance.
+ The system restarts your original instance, and terminates the temporary instance. The system also terminates the temporary VPC and the Lambda functions created at the start of the automation.
## Before you begin
Before you run the following Automation, do the following:
+ Copy the instance ID of the unreachable instance. You will specify this ID in the procedure.
+ Optionally, collect the ID of a subnet in the same availability zone as your unreachable instance. The EC2Rescue instance will be created in this subnet. If you don’t specify a subnet, then Automation creates a new temporary VPC in your AWS account. Verify that your AWS account has at least one VPC available. By default, you can create five VPCs in a Region. If you already created five VPCs in the Region, the automation fails without making changes to your instance. For more information about Amazon VPC quotas, see [VPC and Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-vpcs-subnets) in the *Amazon VPC User Guide*.
+ Optionally, you can create and specify an AWS Identity and Access Management (IAM) role for Automation. If you don't specify this role, then Automation runs in the context of the user who ran the automation.
### Granting `AWSSupport-EC2Rescue` permissions to perform actions on your instances
EC2Rescue needs permission to perform a series of actions on your instances during the automation. These actions invoke the AWS Lambda, IAM, and Amazon EC2 services to safely and securely attempt to remediate issues with your instances. If you have Administrator-level permissions in your AWS account and/or VPC, you might be able to run the automation without configuring permissions, as described in this section. If you don't have Administrator-level permissions, then you or an administrator must configure permissions by using one of the following options.
+ [Granting permissions by using IAM policies](#automation-ec2rescue-access-iam)
+ [Granting permissions by using an CloudFormation template](#automation-ec2rescue-access-cfn)
#### Granting permissions by using IAM policies
You can either attach the following IAM policy to your user, group, or role as an inline policy; or, you can create a new IAM managed policy and attach it to your user, group, or role. For more information about adding an inline policy to your user, group, or role see [Working With Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html). For more information about creating a new managed policy, see [Working With Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html).
**Note**
If you create a new IAM managed policy, you must also attach the **AmazonSSMAutomationRole** managed policy to it so that your instances can communicate with the Systems Manager API.
**IAM Policy for AWSSupport-EC2Rescue**
Replace *account ID* with your own information.
------
#### [ 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*",
"autoscaling:DescribeAutoScalingInstances"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
#### Granting permissions by using an CloudFormation template
CloudFormation automates the process of creating IAM roles and policies by using a preconfigured template. Use the following procedure to create the required IAM roles and policies for the EC2Rescue Automation by using CloudFormation.
**To create the required IAM roles and policies for EC2Rescue**
1. Download [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip) and extract the `AWSSupport-EC2RescueRole.json` file to a directory on your local machine.
1. If your AWS account is in a special partition, edit the template to change the ARN values to those for your partition.
For example, for the China Regions, change all cases of `arn:aws` to `arn:aws-cn`.
1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Choose **Create stack**, **With new resources (standard)**.
1. On the **Create stack** page, for **Prerequisite - Prepare template**, choose **Template is ready**.
1. For **Specify template**, choose **Upload a template file**.
1. Choose **Choose file**, and then browse to and select the `AWSSupport-EC2RescueRole.json` file from the directory where you extracted it.
1. Choose **Next**.
1. On the **Specify stack details** page, for **Stack name** field, enter a name to identify this stack, and then choose **Next**.
1. (Optional) In the **Tags** area, apply one or more tag key name/value pairs to the stack.
Tags are optional metadata that you assign to a resource. Tags enable you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag a stack to identify the type of tasks it runs, the types of targets or other resources involved, and the environment it runs in.
1. Choose **Next**
1. On the **Review** page, review the stack details, and then scroll down and choose the **I acknowledge that CloudFormation might create IAM resources** option.
1. Choose **Create stack**.
CloudFormation shows the **CREATE\$1IN\$1PROGRESS** status for a few minutes. The status changes to **CREATE\$1COMPLETE** after the stack has been created. You can also choose the refresh icon to check the status of the create process.
1. In the **Stacks** list, choose the option button the stack you just created, and then choose the **Outputs** tab.
1. Note the **Value**. The is the ARN of the AssumeRole. You specify this ARN when you run the Automation in the next procedure, [Running the Automation](#automation-ec2rescue-executing).
## Running the Automation
**Important**
The following automation stops the unreachable instance. Stopping the instance can result in lost data on attached instance store volumes (if present). Stopping the instance can also cause the public IP to change, if no Elastic IP is associated.
**To run the `AWSSupport-ExecuteEC2Rescue` Automation**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Automation**.
1. Choose **Execute automation**.
1. In the **Automation document** section, choose **Owned by Amazon** from the list.
1. In the runbooks list, choose the button in the card for `AWSSupport-ExecuteEC2Rescue`, and then choose **Next**.
1. In the **Execute automation document** page, choose **Simple execution**.
1. In the **Document details** section, verify that **Document version** is set to the highest default version. For example, **\$1DEFAULT** or **3 (default)**.
1. In the **Input parameters** section, specify the following parameters:
1. For **UnreachableInstanceId**, specify the ID of the unreachable instance.
1. (Optional) For **EC2RescueInstanceType**, specify an instance type for the EC2Rescue instance. The default instance type is `t2.medium`.
1. For **AutomationAssumeRole**, if you created roles for this Automation by using the CloudFormation procedure described earlier in this topic, then choose the ARN of the AssumeRole that you created in the CloudFormation console.
1. (Optional) For **LogDestination**, specify an S3 bucket if you want to collect operating system-level logs while troubleshooting your instance. Logs are automatically uploaded to the specified bucket.
1. For **SubnetId**, specify a subnet in an existing VPC in the same availability zone as the unreachable instance. By default, Systems Manager creates a new VPC, but you can specify a subnet in an existing VPC if you want.
**Note**
If you don't see the option to specify a bucket or a subnet ID, verify that you are using the latest **Default** version of the runbook.
1. (Optional) In the **Tags** area, apply one or more tag key name/value pairs to help identify the automation, for example `Key=Purpose,Value=EC2Rescue`.
1. Choose **Execute**.
The runbook creates a backup AMI as part of the automation. All other resources created by the automation are automatically deleted, but this AMI remains in your account. The AMI is named using the following convention:
Backup AMI: AWSSupport-EC2Rescue:*UnreachableInstanceId*
You can locate this AMI in the Amazon EC2 console by searching on the Automation execution ID.
# Reset passwords and SSH keys on EC2 instances
You can use the `AWSSupport-ResetAccess` runbook to automatically re-enable local Administrator password generation on Amazon Elastic Compute Cloud (Amazon EC2) instances for Windows Server and to generate a new SSH key on EC2 instances for Linux. The `AWSSupport-ResetAccess` runbook is designed to perform a combination of AWS Systems Manager actions, AWS CloudFormation actions, and AWS Lambda functions that automate the steps normally required to reset the local administrator password.
You can use Automation, a tool in AWS Systems Manager, with the `AWSSupport-ResetAccess` runbook to solve the following problems:
**Windows**
*You lost the EC2 key pair*: To resolve this problem, you can use the **AWSSupport-ResetAccess** runbook to create a password-enabled AMI from your current instance, launch a new instance from the AMI, and select a key pair you own.
*You lost the local Administrator password*: To resolve this problem, you can use the `AWSSupport-ResetAccess` runbook to generate a new password that you can decrypt with the current EC2 key pair.
**Linux**
*You lost your EC2 key pair, or you configured SSH access to the instance with a key you lost*: To resolve this problem, you can use the `AWSSupport-ResetAccess` runbook to create a new SSH key for your current instance, which enables you to connect to the instance again.
**Note**
If your EC2 instance for Windows Server is configured for Systems Manager, you can also reset your local Administrator password by using EC2Rescue and AWS Systems Manager Run Command. For more information, see [Using EC2Rescue for Windows Server with Systems Manager Run Command](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-ssm.html) in the *Amazon EC2 User Guide*.
**Related information**
[Connect to your Linux instance from Windows using PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html) in the *Amazon EC2 User Guide*
## How it works
Troubleshooting an instance with Automation and the `AWSSupport-ResetAccess` runbook works as follows:
+ You specify the ID of the instance and run the runbook.
+ The system creates a temporary VPC, and then runs a series of Lambda functions to configure the VPC.
+ The system identifies a subnet for your temporary VPC in the same Availability Zone as your original instance.
+ The system launches a temporary, SSM-enabled helper instance.
+ The system stops your original instance, and creates a backup. It then attaches the original root volume to the helper instance.
+ The system uses Run Command to run EC2Rescue on the helper instance. On Windows, EC2Rescue enables password generation for the local Administrator by using EC2Config or EC2Launch on the attached, original root volume. On Linux, EC2Rescue generates and injects a new SSH key and saves the private key, encrypted, in Parameter Store. When finished, EC2Rescue reattaches the root volume back to the original instance.
+ The system creates a new Amazon Machine Image (AMI) of your instance, now that password generation is enabled. You can use this AMI to create a new EC2 instance, and associate a new key pair if needed.
+ The system restarts your original instance, and terminates the temporary instance. The system also terminates the temporary VPC and the Lambda functions created at the start of the automation.
+ **Windows**: Your instance generates a new password you can decode from the Amazon EC2 console using the current key pair assigned to the instance.
**Linux**: You can SSH to the instance by using the SSH key stored in Systems Manager Parameter Store as **/ec2rl/openssh/*instance ID*/key**.
## Before you begin
Before you run the following Automation, do the following:
+ Copy the instance ID of the instance on which you want to reset the Administrator password. You will specify this ID in the procedure.
+ Optionally, collect the ID of a subnet in the same availability zone as your unreachable instance. The EC2Rescue instance will be created in this subnet. If you don’t specify a subnet, then Automation creates a new temporary VPC in your AWS account. Verify that your AWS account has at least one VPC available. By default, you can create five VPCs in a Region. If you already created five VPCs in the Region, the automation fails without making changes to your instance. For more information about Amazon VPC quotas, see [VPC and Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-vpcs-subnets) in the *Amazon VPC User Guide*.
+ Optionally, you can create and specify an AWS Identity and Access Management (IAM) role for Automation. If you don't specify this role, then Automation runs in the context of the user who ran the automation.
### Granting AWSSupport-EC2Rescue permissions to perform actions on your instances
EC2Rescue needs permission to perform a series of actions on your instances during the automation. These actions invoke the AWS Lambda, IAM, and Amazon EC2 services to safely and securely attempt to remediate issues with your instances. If you have Administrator-level permissions in your AWS account and/or VPC, you might be able to run the automation without configuring permissions, as described in this section. If you don't have Administrator-level permissions, then you or an administrator must configure permissions by using one of the following options.
+ [Granting permissions by using IAM policies](#automation-ec2reset-access-iam)
+ [Granting permissions by using an CloudFormation template](#automation-ec2reset-access-cfn)
#### Granting permissions by using IAM policies
You can either attach the following IAM policy to your user, group, or role as an inline policy; or, you can create a new IAM managed policy and attach it to your user, group, or role. For more information about adding an inline policy to your user, group, or role see [Working With Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html). For more information about creating a new managed policy, see [Working With Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html).
**Note**
If you create a new IAM managed policy, you must also attach the **AmazonSSMAutomationRole** managed policy to it so that your instances can communicate with the Systems Manager API.
**IAM Policy for `AWSSupport-ResetAccess`**
Replace *account ID* with your own information.
------
#### [ 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"
}
]
}
```
------
#### Granting permissions by using an CloudFormation template
CloudFormation automates the process of creating IAM roles and policies by using a preconfigured template. Use the following procedure to create the required IAM roles and policies for the EC2Rescue Automation by using CloudFormation.
**To create the required IAM roles and policies for EC2Rescue**
1. Download [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip) and extract the `AWSSupport-EC2RescueRole.json` file to a directory on your local machine.
1. If your AWS account is in a special partition, edit the template to change the ARN values to those for your partition.
For example, for the China Regions, change all cases of `arn:aws` to `arn:aws-cn`.
1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Choose **Create stack**, **With new resources (standard)**.
1. On the **Create stack** page, for **Prerequisite - Prepare template**, choose **Template is ready**.
1. For **Specify template**, choose **Upload a template file**.
1. Choose **Choose file**, and then browse to and select the `AWSSupport-EC2RescueRole.json` file from the directory where you extracted it.
1. Choose **Next**.
1. On the **Specify stack details** page, for **Stack name** field, enter a name to identify this stack, and then choose **Next**.
1. (Optional) In the **Tags** area, apply one or more tag key name/value pairs to the stack.
Tags are optional metadata that you assign to a resource. Tags enable you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag a stack to identify the type of tasks it runs, the types of targets or other resources involved, and the environment it runs in.
1. Choose **Next**
1. On the **Review** page, review the stack details, and then scroll down and choose the **I acknowledge that CloudFormation might create IAM resources** option.
1. CloudFormation shows the **CREATE\$1IN\$1PROGRESS** status for a few minutes. The status changes to **CREATE\$1COMPLETE** after the stack has been created. You can also choose the refresh icon to check the status of the create process.
1. In the stack list, choose the option next to the stack you just created, and then choose the **Outputs** tab.
1. Copy the **Value**. The is the ARN of the AssumeRole. You will specify this ARN when you run the Automation.
## Running the Automation
The following procedure describes how to run the `AWSSupport-ResetAccess` runbook by using the AWS Systems Manager console.
**Important**
The following automation stops the instance. Stopping the instance can result in lost data on attached instance store volumes (if present). Stopping the instance can also cause the public IP to change, if no Elastic IP is associated. To avoid these configuration changes, use Run Command to reset access. For more information, see [Using EC2Rescue for Windows Server with Systems Manager Run Command](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-ssm.html) in the *Amazon EC2 User Guide*.
**To run the AWSSupport-ResetAccess Automation**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Automation**.
1. Choose **Execute automation**.
1. In the **Automation document** section, choose **Owned by Amazon** from the list.
1. In the runbooks list, choose the button in the card for **AWSSupport-ResetAccess**, and then choose **Next**.
1. In the **Execute automation document** page, choose **Simple execution**.
1. In the **Document details** section, verify that **Document version** is set to the highest default version. For example, **\$1DEFAULT** or **3 (default)**.
1. In the **Input parameters** section, specify the following parameters:
1. For **InstanceID**, specify the ID of the unreachable instance.
1. For **SubnetId**, specify a subnet in an existing VPC in the same availability zone as the instance you specified. By default, Systems Manager creates a new VPC, but you can specify a subnet in an existing VPC if you want.
**Note**
If you don't see the option to specify a subnet ID, verify that you are using the latest **Default** version of the runbook.
1. For **EC2RescueInstanceType**, specify an instance type for the EC2Rescue instance. The default instance type is `t2.medium`.
1. For **AssumeRole**, if you created roles for this Automation by using the CloudFormation procedure described earlier in this topic, then specify the AssumeRole ARN that you noted in the CloudFormation console.
1. (Optional) In the **Tags** area, apply one or more tag key name/value pairs to help identify the automation, for example `Key=Purpose,Value=ResetAccess`.
1. Choose **Execute**.
1. To monitor the automation progress, choose the running automation, and then choose the **Steps** tab. When the automation is finished, choose the **Descriptions** tab, and then choose **View output** to view the results. To view the output of individual steps, choose the **Steps** tab, and then choose **View Outputs** next to a step.
The runbook creates a backup AMI and a password-enabled AMI as part of the automation. All other resources created by the automation are automatically deleted, but these AMIs remain in your account. The AMIs are named using the following conventions:
+ Backup AMI: `AWSSupport-EC2Rescue:InstanceID`
+ Password-enabled AMI: AWSSupport-EC2Rescue: Password-enabled AMI from *Instance ID*
You can locate these AMIs by searching on the Automation execution ID.
For Linux, the new SSH private key for your instance is saved, encrypted, in Parameter Store. The parameter name is **/ec2rl/openssh/*instance ID*/key**.
# Passing data to Automation using input transformers
This AWS Systems Manager Automation tutorial shows how to use the input transformer feature of Amazon EventBridge to extract the `instance-id` of an Amazon Elastic Compute Cloud (Amazon EC2) instance from an instance state change event. Automation is a tool in AWS Systems Manager. We use the input transformer to pass that data to the `AWS-CreateImage` runbook target as the `InstanceId` input parameter. The rule is triggered when any instance changes to the `stopped` state.
For more information about working with input transformers, see [Tutorial: Use Input Transformer to Customize What is Passed to the Event Target](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-input-transformer-tutorial.html) in the *Amazon EventBridge User Guide*.
**Before you begin**
Verify that you added the required permissions and trust policy for EventBridge to your Systems Manager Automation service role. For more information, see [Overview of Managing Access Permissions to Your EventBridge Resources](https://docs.aws.amazon.com/eventbridge/latest/userguide/iam-access-control-identity-based-eventbridge.html) in the *Amazon EventBridge User Guide*.
**To use input transformers with Automation**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. Enter a name and description for the rule.
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to respond to matching events that come from your own AWS account, select **default**. When an AWS service in your account emits an event, it always goes to your account’s default event bus.
1. For **Rule type**, choose **Rule with an event pattern**.
1. Choose **Next**.
1. For **Event source**, choose **AWS events or EventBridge partner events**.
1. In the **Event pattern** section, choose **Use pattern form**.
1. For **Event source**, choose **AWS services**.
1. For **AWS service**, choose **EC2**.
1. For **Event type**, choose **EC2 Instance State-change Notification**.
1. For **Event Type Specification 1**, select **Specific state(s)**, and then choose **stopped**.
1. For **Event Type Specification 2**, select **Any instance**, or select **Specific instance Id(s)** and enter the IDs of the instances to monitor.
1. Choose **Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, choose **Systems Manager Automation**.
1. For **Document**, choose **AWS-CreateImage**.
1. In the **Configure automation parameter(s)** section, choose **Input Transformer**.
1. For **Input path**, enter **\$1"instance":"\$1.detail.instance-id"\$1**.
1. For **Template**, enter **\$1"InstanceId":[]\$1**.
1. For **Execution role**, choose **Use existing role** and choose your Automation service role.
1. Choose **Next**.
1. (Optional) Enter one or more tags for the rule. For more information, see [Tagging Your Amazon EventBridge Resources](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-tagging.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. Review the details of the rule and choose **Create rule**.