Menu
Amazon EC2 Systems Manager
User Guide

Working with Predefined Automation Documents

To help you get started quickly, Systems Manager provides a pre-defined Automation document that is maintained by Amazon Web Services. The document is named AWS-UpdateLinuxAmi. This document enables you to automate image-maintenance tasks without having to author the workflow in JavaScript Object Notation (JSON). You can use the AWS-UpdateLinuxAmi document to perform the following types of tasks.

  • Upgrade all distribution packages and Amazon software on an Amazon Linux, Red Hat, Ubuntu, or Cent OS Amazon Machine Image (AMI). This is the default document behavior.

  • Install the SSM Agent on an existing image to enable Systems Manager capabilities, such as remote command execution using Run Command or software inventory collection using Inventory.

  • Install additional software packages.

You can view the JSON for this document in the Amazon EC2 console. Expand Systems Manager Shared Resources, and then choose Documents. Choose the option beside the AWS-UpdateLinuxAmi document, and then use the tabs in the lower pane to view the JSON and other information about the document, as shown in the following image.


                        Systems Manager Automation document

The AWS-UpdateLinuxAmi document accepts the following input parameters.

Parameter Type Description

SourceAmiId

String

(Required) The source AMI ID.

InstanceIamRole

String

(Required) The name of the AWS Identity and Access Management (IAM) instance profile role you created in Setting Up Automation. The instance profile role gives Automation permission to perform actions on your instances, such as executing commands or starting and stopping services. The Automation document uses only the name of the instance profile role. If you specify the Amazon Resource Name (ARN), the Automation execution fails.

AutomationAssumeRole

String

(Required) The name of the IAM service role you created in Setting Up Automation. 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 executing the aws:createImage action in an Automation document. 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 (\"none\") is to not run a script.

PostUpdateScript

String

(Optional) URL of a script to run after package updates are applied. Default (\"none\") is to not run a script.

IncludePackages

String

(Optional) Only update these named packages. By default (\"all\"), all available updates are applied.

ExcludePackages

String

(Optional) Names of packages to hold back from updates, under all conditions. By default (\"none\"), no package is excluded.

Automation Steps

The AWS-UpdateLinuxAmi document includes the following Automation steps, by default.

Step 1: launchInstance (aws:runInstances action)

This step launches an instance using Amazon EC2 userdata and an IAM instance profile role. Userdata installs the appropriate SSM Agent, based on the operating system. Installing the SSM Agent enables you to utilize Systems Manager capabilities such as Run Command, State Manager, and Inventory.

Step 2: updateOSSoftware (aws:runCommand action)

This step executes the following commands on the launched instance:

  • Downloads an update script from Amazon S3.

  • Executes an optional pre-update script.

  • Updates distribution packages and Amazon software.

  • Executes 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 {{global:DATE_TIME}} from {{SourceAmiId}}” where DATE_TIME and SourceID represent Automation variables.

Step 5: terminateInstance (aws:changeInstanceState action)

This step cleans up the execution by terminating the running instance.

Output

The execution returns the new AMI ID as output.

You can use the AWS-UpdateLinuxAmi document as a template to create your own document, as described in the next section. For information about actions (steps) that are supported in Automation documents, see Systems Manager Automation Actions. For information about how to use Automation documents, see Systems Manager Automation Walkthroughs