Menu
Amazon EC2 Systems Manager
User Guide

Automation CLI Walkthrough: Patch a Linux AMI

This Systems Manager Automation walkthrough shows you how to use the AWS CLI and the Systems Manager AWS-UpdateLinuxAmi document to automatically patch a Linux AMI. You can update any of the following Linux versions using this walkthrough: Ubuntu, CentOS, RHEL, or Amazon Linux AMIs. The AWS-UpdateLinuxAmi document also automates the installation of additional site-specific packages and configurations.

When you run the AWS-UpdateLinuxAmi document, Automation performs the following tasks.

  1. Launches a temporary Amazon EC2 instance from a Linux AMI. The instance is configured with a User Data script that installs the SSM Agent. The SSM Agent executes scripts sent remotely from Systems Manager Run Command.

  2. Updates the Instance by performing the following actions:

    1. Invokes a user-provided pre-update script on the instance.

    2. Updates AWS tools on the instance, if any tools are present.

    3. Updates distribution packages on the instance by using the native package manager.

    4. Invokes a user-provided post-update script on the instance.

  3. Stops the temporary instance.

  4. Creates a new AMI from the stopped instance.

  5. Terminates the instance.

After Automation successfully completes this workflow, the new AMI is available in the Amazon EC2 console on the AMIs page.

Important

If you use Automation to create an AMI from an instance, be aware that credentials, passwords, data, or other confidential information on the instance are recorded on the new image. Use caution when creating an AMI from an instance.

As you get started with Automation, note the following restrictions.

  • Automation does not perform resource clean-up. In the event your workflow stops before reaching the final instance-termination step in the example workflow, you might need to stop instances manually or disable services that were started during the Automation workflow.

  • If you use userdata with Automation, the userdata must be base-64 encoded.

  • Automation retains execution records for 30 days.

  • Systems Manager and Automation have the following service limits.

To create a patched AMI using Automation

  1. Collect the following information. You will specify this information later in this procedure.

    • The source ID of the AMI to update.

    • An AWS Identity and Access Management (IAM) instance profile role that gives Automation permission to perform actions on your instances. For more information, see Method 2: Using IAM to Configure Roles for Automation.

    • An IAM service role for Automation (assume role) that Automation uses to perform actions on your behalf. For more information, see Setting Up Automation.

  2. Download the AWS CLI to your local machine.

  3. Execute the following command to run the AWS-UpdateLinuxAmi document and run the Automation workflow. In the parameters section, specify your Automation role, an AMI source ID, and an Amazon EC2 instance role.

    Copy
    aws ssm start-automation-execution \ --document-name "AWS-UpdateLinuxAmi" \ --parameters \ "AutomationAssumeRole=arn:aws:iam::1234561213:role/MyAutomationRole, SourceAmiId=ami-e6d5d2f1, InstanceIamRole=MyEc2InstanceProfileRole"

    The command returns an execution ID. Copy this ID to the clipboard. You will use this ID to view the status of the workflow.

    Copy
    { "AutomationExecutionId": "ID" }
  4. To view the workflow execution using the CLI, execute the following command:

    Copy
    aws ssm describe-automation-executions
  5. To view details about the execution progress, execute the following command.

    Copy
    aws ssm get-automation-execution --automation-execution-id ID

    The update process can take 30 minutes or more to complete.

    Note

    You can also monitor the status of the workflow in the Amazon EC2 console. In the execution list, choose the execution you just ran and then choose the Steps tab. This tab shows you the status of the workflow actions.

After the workflow finishes, launch a test instance from the updated AMI to verify changes.

Note

If any step in the workflow fails, information about the failure is listed on the Automation Executions page. The workflow 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.