Component manager supported action modules - EC2 Image Builder

Component manager supported action modules

This section contains the list of action modules that are supported by the component management application used by EC2 Image Builder to configure the instance that builds your image. Also included are the corresponding functionality details and input/output values of the action modules.

Note

All action modules are run by using the same account as the SSM agent, which is root on Linux and NT Authority\SYSTEM on Windows.

ExecuteBinary

The ExecuteBinary module allows you to run binary files with a list of command-line arguments.

The ExecuteBinary module handles system restarts if the run finishes with an exit code of 194 (Linux) or 3010 (Windows). When triggered, the application performs one of the following actions:

  • The application hands the exit code to the caller if it is executed by the SSM Agent. The SSM Agent handles the system restart and re-invokes the execution as described in Rebooting Managed Instance from Scripts.

  • The application saves the current executionstate, configures a restart initiation to rerun the application, and restarts the system.

After the system restarts, the application runs the same step that initiated the restart. If you require this functionality, you must write idempotent scripts that can handle multiple invocations of the same shell command.

Input
Primitive Description Type Required
path The path to the binary file for running. String Yes
arguments Contains a list of command-line arguments to use when running the binary. String List No

Input example

name: "InstallDotnet" action: ExecuteBinary inputs: path: C:\PathTo\dotnet_installer.exe arguments: - /qb - /norestart
Output
Field Description Type
stdout Standard output from the running of a command. string

Output example

{ "stdout": "success" }

ExecuteBash

The ExecuteBash module allows you to run bash scripts with inline shell code/commands. This module supports Linux.

All of the commands and instructions that you specify in the commands block are converted into a file (for example, input.sh) and run by using the bash shell. The result of running shell file is the exit code of the step.

The ExecuteBash module handles system restarts if the run finishes with an exit code of 194. When initiated, the application performs one of the following actions:

  • The application hands the exit code to the caller if it is run by the SSM Agent. The SSM Agent handles the system restart and re-invokes the execution as described in Rebooting Managed Instance from Scripts.

  • The application saves the current executionstate, configures a restart initiation to rerun the application, and restarts the system.

After the system restarts, the application runs the same step that initiated the restart. If you require this functionality, you must write idempotent scripts that can handle multiple invocations of the same shell command.

Input
Primitive Description Type Required
commands Contains a list of instructions or commands to run, according to bash syntax. Multi-line YAML is allowed. List Yes

Input example

name: InstallAndValidateCorretto action: ExecuteBash inputs: commands: - sudo yum install java-11-amazon-corretto-headless -y - | function fail_with_message() { 1>&2 echo $1 exit 1 } ARCH=`/usr/bin/arch` JAVA_PATH=/usr/lib/jvm/java-11-amazon-corretto.$ARCH/bin/java if [ -x $JAVA_PATH ]; then echo "Amazon Corretto 11 JRE is installed." else fail_with_message "Amazon Corretto 11 JRE is not installed. Failing." fi JAVAC_PATH=/usr/lib/jvm/java-11-amazon-corretto.$ARCH/bin/javac if [ -x $JAVAC_PATH ]; then echo "Amazon Corretto 11 JDK is installed." else fail_with_message "Amazon Corretto 11 JDK is not installed. Failing." fi
Output
Field Description Type
stdout Standard output from running a command. string

Output example

{ “stdout”: “This is the standard output from the shell execution\n" }

If you initiate a restart and return exit code 194 as part of the action module, the build will resume at the same action module step that initiated the restart. If you restart without the exit code, the build process may fail.

ExecutePowerShell

The ExecutePowerShell module allows you to run PowerShell scripts with inline shell code/commands. This module supports the Windows platform and Windows PowerShell.

All of the commands/instructions specified in the commands block are converted into a script file (for example, input.ps1) and run by using Windows PowerShell. The result of the shell file execution is the exit code.

The ExecutePowerShell module handles system restarts if the shell command exits with an exit code of 3010. When initiated, the application performs one of the following actions:

  • Hands the exit code to the caller if run by the SSM Agent. The SSM Agent handles the system restart and re-invokes the execution as described in Rebooting Managed Instance from Scripts.

  • Saves the current executionstate, configures a restart initiation to rerun the application, and restarts the system.

After the system restarts, the application runs the same step that initiated the restart. If you require this functionality, you must write idempotent scripts that can handle multiple invocations of the same shell command.

Input
Primitive Description Type Required
commands Contains a list of instructions or commands to run, according to PowerShell syntax. Multi-line YAML is allowed. String List

Yes

Must specify commands or file, not both.

file Contains the path to a PowerShell script file. PowerShell will run against this file using the -file command line argument. The path must point to a .ps1 file. String

Yes

Must specify commands or file, not both.

Input example

name: InstallMySoftware action: ExecutePowerShell inputs: commands: - Set-SomeConfiguration -Value 10 - Write-Host 'Successfully set the configuration.' name: ExecuteMyScript action: ExecutePowerShell inputs: file: 'C:\PathTo\MyScript.ps1'
Output
Field Description Type
stdout Standard output from running a command. string

Output example

{ “stdout”: “This is the standard output from the shell execution\n" }

If you initiate a restart and return exit code 3010 as part of the action module, the build will resume at the same action module step that initiated the restart. If you restart without the exit code, the build process may fail.

Reboot

The Reboot action module restarts the instance. It has a configurable option to delay the restart. It does not support the step timeout value because of the instance getting restarted. Default behavior is that delaySeconds is 0, which means that there is no delay.

If the application is invoked by the SSM Agent, it hands the exit code (3010 for Windows, 194 for Linux) to the SSM Agent. The SSM Agent handles the system restart as described in Rebooting Managed Instance from Scripts.

If the application is invoked on the host as a standalone process, it saves the current run state, configures a post-reboot auto-run trigger to rerun the application, and then restarts the system.

Post-reboot auto-run trigger:

  • Windows. Create a Task Scheduler entry with a trigger at SystemStartup

  • Linux. Add a job in crontab.

@reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml

This trigger is cleaned up when the application starts.

To use the Reboot action module, for steps that contain reboot exitcode (for example, 3010), you must run the application binary as sudo user.

Input
Primitive Description Type Required Default
delaySeconds Delays a specific amount of time before initiating a restart. Integer

No

0

Input example

name: RebootStep action: Reboot onFailure: Abort maxAttempts: 2 inputs: delaySeconds: 60

Output

None.

When the Reboot module completes, Image Builder continues to the next step in the build.

UpdateOS

The UpdateOS action module adds support for installing Windows and Linux updates.

The UpdateOS action module installs all available updates by default. You can override this action by providing a list of one or more updates to include for installation, a list of one or more updates to exclude from installation, or both.

If both “include" and "exclude" lists are provided, the resulting list of updates can include only those listed in the "include" list that are not listed in the "exclude" list.

  • Windows. Updates are installed from the update source configured on the target machine.

  • Linux. The application checks for the supported package manager in the Linux platform and uses either yum or apt-get package manager. If neither is supported, an error is returned. You should have sudo permissions to run the UpdateOS action module. If you do not have sudo permissions an error.Input is returned.

Input
Primitive Description Type Required
include

For Windows, you can specify the following:

  • One or more Microsoft Knowledge Base (KB) article IDs to include in the list of updates that may be installed. Valid formats are KB1234567 or 1234567.

  • An update name using a wildcard value (*). Valid formats are Security* or *Security*.

For Linux, you can specify one or more packages to be included in the list for installation.

String List No
exclude

For Windows, you can specify the following:

  • One or more Microsoft Knowledge Base (KB) article IDs to include in the list of updates to be excluded from the installation. Valid formats are KB1234567 or 1234567.

  • An update name using a wildcard (*) value. Valid formats are: Security* or *Security*.

For Linux, you can specify one or more packages to be excluded from the installation.

String List No

Input example: Linux

name: UpdateMyLinux action: UpdateOS onFailure: Abort maxAttempts: 3 inputs: exclude: - ec2-hibinit-agent

Input example: Windows

name: UpdateWindowsOperatingSystem action: UpdateOS onFailure: Abort maxAttempts: 3 inputs: include: - KB1234567 - '*Security*'

Output

None.

S3Upload

The S3Upload action module allows you to upload a file from a source file/folder to an Amazon S3 location. Wildcards are permitted for use with the source and are denoted by the character *. If the specified destination object already exists in the target Amazon S3 bucket, S3Upload overwrites the object.

If the recursive S3Upload action fails, Amazon S3 files that have already been uploaded will remain.

Supported use cases:

• Local file to S3 object.

• Local files in folder (with wildcard) to S3 KeyPrefix.

• Copy local folder (must have recurse set to true) to S3 KeyPrefix.

IAM requirements

The IAM role that you associate with your instance profile must have permissions to run the S3Upload action module. The following IAM role policy must be attached to the IAM role that is associated with the instance profile: s3:PutObject against the bucket/object (for example, arn:aws:s3:::BucketName/*).

Input
Primitive Description Type Required Default
source Local path. Source supports wildcard denoted by a *. String

Yes

destination Remote path. String

Yes

recurse When set to true, performs S3Upload recursively. String No false

Input example: Copy local file to S3 object

The following example shows how to copy a local file to an S3 object.

name: MyS3UploadFile action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\package.zip destination: s3://mybucket/path/to/package.zip

Input example: Copy all files in local folder to S3 bucket with KeyPrefix

The following example shows how to copy all files in the local folder to an S3 bucket with KeyPrefix. This example does not copy subfolders or their contents because recurse is not specified, and it defaults to false.

name: MyS3UploadMultipleFiles action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\* destination: s3://mybucket/path/to/

Input example: Copy all files and folders recursively from a local folder to S3 Bucket

The following example shows how to copy all files and folders recursively from a local folder to an Amazon S3 bucket with KeyPrefix.

name: MyS3UploadFolder action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\* destination: s3://mybucket/path/to/ recurse: true

Output

None.

S3Download

The S3Download action module allows you to download an Amazon S3object or a set of Amazon S3 objects from a KeyPrefix to a local destination path. The destination path can be a file or folder. If the specified destination file already exists on the local system, S3Download overwrites the file.

If the S3Download action for S3KeyPrefix fails, the state of the destination folder remains as it is upon failure. The folder contents are not rolled back to the contents before failure.

Supported use cases:

  • S3 object to local file.

  • S3 objects (with KeyPrefix in an Amazon S3 file path) to local folder, which recursively copies all Amazon S3 files in a KeyPrefix to the local folder.

IAM requirements

The IAM role that you associate with your instance profile must have permissions to run the S3Download action module. The following IAM role policies must be attached to the IAM role that is associated with the instance profile:

  • Single file: s3:GetObject against the bucket/object (for example, arn:aws:s3:::BucketName/*).

  • Multiple files: s3:ListBucket against the bucket/object (for example, arn:aws:s3:::BucketName) and s3:GetObject against the bucket/object (for example, arn:aws:s3:::BucketName/*).

Input
Primitive Description Type Required
source Remote path. Source supports wildcard denoted by a *. String

Yes

destination Local path. String Yes
Note

For the following examples, the Windows folder path can be replaced with a Linux path. For example, C:\myfolder\package.zip can be replaced with /myfolder/package.zip.

Input example: Copy S3 object to local file

The following example shows how to copy an S3 object to a local file.

name: DownloadMyFile action: S3Download inputs: - source: s3://mybucket/path/to/package.zip destination: C:\myfolder\package.zip

Input example: Copy all S3 objects in S3 bucket with KeyPrefix to local folder

The following example shows how to copy all S3 objects in an S3 bucket with the KeyPrefix to a local folder. Amazon S3 has no concept of a folder; therefore, all objects matching the KeyPrefix are copied. The limit for maximum objects is 1000.

name: MyS3DownloadKeyprefix action: S3Download maxAttempts: 3 inputs: - source: s3://mybucket/path/to/* destination: C:\myfolder\

Output

None.

SetRegistry

The SetRegistry action module accepts a list of inputs and allows you to set the value for the specified registry key. If a registry key does not exist, it is created in the defined path. This feature applies only to Windows.

Input
Primitive Description Type Required
path Path of the registry key. String Yes
name Name of the registry key. String Yes
value Value of the registry key. String/Number/Array Yes
type Value type of the registry key. String Yes

Supported path prefixes

  • HKEY_CLASSES_ROOT / HKCR:

  • HKEY_USERS / HKU:

  • HKEY_LOCAL_MACHINE / HKLM:

  • HKEY_CURRENT_CONFIG / HKCC:

  • HKEY_CURRENT_USER / HKCU:

Supported types

  • BINARY

  • DWORD

  • QWORD

  • SZ

  • EXPAND_SZ

  • MULTI_SZ

Input example

name: SetRegistryKeyValues action: SetRegistry maxAttempts: 3 inputs: - path: HKLM:\SOFTWARE\MySoftWare name: MyName value: FirstVersionSoftware type: SZ - path: HKEY_CURRENT_USER\Software\Test name: Version value: 1.1 type: DWORD

Output

None.