Action modules supported by AWSTOE component manager

Image building services, such as EC2 Image Builder, use AWSTOE action modules to help configure the EC2 instances that are used for building and testing customized machine images. This section describes the features of commonly used AWSTOE action modules, and how to configure them, including examples.

Components are authored with plaintext YAML documents. For more information about document syntax, see Use the AWSTOE component document framework for custom components.

The following cross-reference categorizes action modules by the type of actions that they perform.

 

 

 

 

 

General execution modules

The following section contains details for action modules that run commands and control execution workflow.

Assert (Linux, Windows, macOS)

The Assert action module performs value comparisons using Comparison operators or Logical operators as input. The result of the operator expression (true or false) indicates the overall success or failure status for the step.

If the comparison or logical operator expression evaluates to true, the step is marked as Success. Otherwise, the step is marked as Failed. If the step fails, the onFailure parameter decides the outcome of the step.

Input example: A simple comparison using the stringEquals comparison operator

This example evaluates to true.

- name: StringComparison
  action: Assert
  inputs:
    stringEquals: '2.1.1'
    value: '{{ validate.ApplicationVersion.outputs.stdout }}'

Input example: Regex comparisons using the patternMatches comparison operator

These examples all evaluate to true.

- name: Letters only
  action: Assert
  inputs:
    patternMatches: '^[a-zA-Z]+$'
    value: 'ThisIsOnlyLetters'

- name: Letters and spaces only
  action: Assert
  inputs:
    patternMatches: '^[a-zA-Z\s]+$'
    value: 'This text contains spaces'
  
- name: Numbers only
  action: Assert
  inputs:
    patternMatches: '^[0-9]+$'
    value: '1234567890'

Input example: Nested comparisons with logical operators and chained variables

The following example demonstrates nested comparisons with logical operators that use comparisons with chained variables. The Assert evaluates to true if either of the following are true:

- name: NestedComparisons
  action: Assert
  inputs:
    or: # <- first level deep
      - and: # <- second level deep
          - numberGreaterThan: 2.0 # <- third level deep
            value: '{{ validate.ApplicationVersion.outputs.stdout }}'
          - stringEquals: 'arm64'
            value: '{{ validate.CPUArchitecture.outputs.stdout }}'
      - stringEquals: 'x86_64'
        value: '{{ validate.CPUArchitecture.outputs.stdout }}'

Output:

The output of an Assert is success or failure of the step.

ExecuteBash (Linux, macOS)

The ExecuteBash action 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 with the bash shell. The result of running the shell file is the exit code of the step.

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

After system restart, 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 example: Before and after a reboot

name: ExitCode194Example
description: This shows how the exit code can be used to restart a system with ExecuteBash
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: RestartTrigger
        action: ExecuteBash
        inputs:
          commands:
            - |
              REBOOT_INDICATOR=/var/tmp/reboot-indicator
              if [ -f "${REBOOT_INDICATOR}" ]; then
                echo 'The reboot file exists. Deleting it and exiting with success.'
                rm "${REBOOT_INDICATOR}"
                exit 0
              fi
              echo 'The reboot file does not exist. Creating it and triggering a restart.'
              touch "${REBOOT_INDICATOR}"
              exit 194

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

Output example: Before reboot (first time through document)

{
	“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}

Output example: After reboot, (second time through document)

{
	“stdout”: “The reboot file exists. Deleting it and exiting with success."
}

ExecuteBinary (Linux, Windows, macOS)

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

The ExecuteBinary module handles system restarts if the binary file exits with an exit code of 194 (Linux) or 3010 (Windows). When this happens, the application performs one of the following actions:

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 example: install .NET

  - name: "InstallDotnet"
    action: ExecuteBinary
    inputs:
      path: C:\PathTo\dotnet_installer.exe
      arguments:
        - /qb
        - /norestart

Output example

{
	"stdout": "success"
}

ExecuteDocument (Linux, Windows, macOS)

The ExecuteDocument action module adds support for nested component documents, running multiple component documents from one document. AWSTOE validates the document that is passed in the input parameter at run time.

If a component document tries to run itself, or to run any of the component documents that are higher up in the current chain of execution, the execution fails.

Input

Parameter map input

Input examples

The following examples show variations of the inputs for your component document, depending on your installation path.

Input example: Local document path

# main.yaml
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: ExecuteNestedDocument
        action: ExecuteDocument
        inputs:
          document: Sample-1.yaml
          phases: build
          parameters:
            - name: parameter-1
              value: value-1
            - name: parameter-2
              value: value-2

Input example: S3 URI as a document path

# main.yaml
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: ExecuteNestedDocument
        action: ExecuteDocument
        inputs:
          document: s3://my-bucket/Sample-1.yaml
          document-s3-bucket-owner: 123456789012
          phases: build,validate
          parameters:
            - name: parameter-1
              value: value-1
            - name: parameter-2
              value: value-2

Input example: EC2 Image Builder component ARN as a document path

# main.yaml
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: ExecuteNestedDocument
        action: ExecuteDocument
        inputs:
          document: arn:aws:imagebuilder:us-west-2:aws:component/Sample-Test/1.0.0
          phases: test
          parameters:
            - name: parameter-1
              value: value-1
            - name: parameter-2
              value: value-2

Using a ForEach loop to run documents

# main.yaml
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: ExecuteNestedDocument
        action: ExecuteDocument
        loop:
          name: 'myForEachLoop'
          forEach:
            - Sample-1.yaml
            - Sample-2.yaml
        inputs:
          document: "{{myForEachLoop.value}}"
          phases: test
          parameters:
            - name: parameter-1
              value: value-1
            - name: parameter-2
              value: value-2

Using a For loop to run documents

# main.yaml
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: ExecuteNestedDocument
        action: ExecuteDocument
        loop:
          name: 'myForLoop'
          for:
            start: 1
            end: 2
            updateBy: 1
        inputs:
          document: "Sample-{{myForLoop.value}}.yaml"
          phases: test
          parameters:
            - name: parameter-1
              value: value-1
            - name: parameter-2
              value: value-2

Output

AWSTOE creates an output file called detailedoutput.json every time it runs. The file contains details about every phase and step of every component document that is invoked while it's running. For the ExecuteDocument action module, you can find a brief runtime summary in the outputs field, and details about the phases, steps, and documents that it runs in the detailedOutput.

{
	\"executedStepCount\":1,\"executionId\":\"97054e22-06cc-11ec-9b14-acde48001122\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"
}",

Each component document's output summary object contains the following details, as shown here, with sample values:

Output example

The following example shows output from the ExecuteDocument action module when a nested execution occurs. In this example, the main.yaml component document successfully runs the Sample-1.yaml component document.

{
    "executionId": "12345a67-89bc-01de-2f34-abcd56789012",
    "status": "success",
    "startTime": "2021-08-26T17:20:31-07:00",
    "endTime": "2021-08-26T17:20:31-07:00",
    "failureMessage": "",
    "documents": [
        {
            "name": "",
            "filePath": "main.yaml",
            "status": "success",
            "description": "",
            "startTime": "2021-08-26T17:20:31-07:00",
            "endTime": "2021-08-26T17:20:31-07:00",
            "failureMessage": "",
            "phases": [
                {
                    "name": "build",
                    "status": "success",
                    "startTime": "2021-08-26T17:20:31-07:00",
                    "endTime": "2021-08-26T17:20:31-07:00",
                    "failureMessage": "",
                    "steps": [
                        {
                            "name": "ExecuteNestedDocument",
                            "status": "success",
                            "failureMessage": "",
                            "timeoutSeconds": -1,
                            "onFailure": "Abort",
                            "maxAttempts": 1,
                            "action": "ExecuteDocument",
                            "startTime": "2021-08-26T17:20:31-07:00",
                            "endTime": "2021-08-26T17:20:31-07:00",
                            "inputs": "[{\"document\":\"Sample-1.yaml\",\"document-s3-bucket-owner\":\"\",\"phases\":\"\",\"parameters\":null}]",
                            "outputs": "[{\"executedStepCount\":1,\"executionId\":\"98765f43-21ed-09cb-8a76-fedc54321098\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"}]",
                            "loop": null,
                            "detailedOutput": [
                                {
                                    "executionId": "98765f43-21ed-09cb-8a76-fedc54321098",
                                    "status": "success",
                                    "startTime": "2021-08-26T17:20:31-07:00",
                                    "endTime": "2021-08-26T17:20:31-07:00",
                                    "failureMessage": "",
                                    "documents": [
                                        {
                                            "name": "",
                                            "filePath": "Sample-1.yaml",
                                            "status": "success",
                                            "description": "",
                                            "startTime": "2021-08-26T17:20:31-07:00",
                                            "endTime": "2021-08-26T17:20:31-07:00",
                                            "failureMessage": "",
                                            "phases": [
                                                {
                                                    "name": "build",
                                                    "status": "success",
                                                    "startTime": "2021-08-26T17:20:31-07:00",
                                                    "endTime": "2021-08-26T17:20:31-07:00",
                                                    "failureMessage": "",
                                                    "steps": [
                                                        {
                                                            "name": "ExecuteBashStep",
                                                            "status": "success",
                                                            "failureMessage": "",
                                                            "timeoutSeconds": 7200,
                                                            "onFailure": "Abort",
                                                            "maxAttempts": 1,
                                                            "action": "ExecuteBash",
                                                            "startTime": "2021-08-26T17:20:31-07:00",
                                                            "endTime": "2021-08-26T17:20:31-07:00",
                                                            "inputs": "[{\"commands\":[\"echo \\\"Hello World!\\\"\"]}]",
                                                            "outputs": "[{\"stdout\":\"Hello World!\"}]",
                                                            "loop": null,
                                                            "detailedOutput": null
                                                        }]
                                                }]
                                        }]
                                }]
                        }]
                
                }]
        }]
}

ExecutePowerShell (Windows)

The ExecutePowerShell action 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 using Windows PowerShell. The result of running the shell file 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:

After system restart, 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 example: Before and after a reboot

name: ExitCode3010Example
description: This shows how the exit code can be used to restart a system with ExecutePowerShell
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: RestartTrigger
        action: ExecutePowerShell
        inputs:
          commands:
            - |
              $rebootIndicator = Join-Path -Path $env:SystemDrive -ChildPath 'reboot-indicator'
              if (Test-Path -Path $rebootIndicator) {
                Write-Host 'The reboot file exists. Deleting it and exiting with success.'
                Remove-Item -Path $rebootIndicator -Force | Out-Null
                [System.Environment]::Exit(0)
              }
              Write-Host 'The reboot file does not exist. Creating it and triggering a restart.'
              New-Item -Path $rebootIndicator -ItemType File | Out-Null
              [System.Environment]::Exit(3010)

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

Output example: Before reboot (first time through document)

{
	“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}

Output example: After reboot, (second time through document)

{
	“stdout”: “The reboot file exists. Deleting it and exiting with success."
}

File download and upload modules

The following section contains details for action modules that upload or download files.

S3Download (Linux, Windows, macOS)

With the S3Download action module, you can download an Amazon S3 object, or a set of objects, to a local file or folder that you specify with the destination path. If any file already exists in the specified location, and the overwrite flag is set to true, S3Download overwrites the file.

Your source location can point to a specific object in Amazon S3, or you can use a key prefix with an asterisk wildcard (*) to download a set of objects that match the key prefix path. When you specify a key prefix in your source location, the S3Download action module downloads everything that matches the prefix (files and folders included). Make sure that the key prefix ends with a forward-slash, followed by an asterisk (/*), so that you download everything that matches the prefix. For example: s3://my-bucket/my-folder/*.

If the S3Download action for a specified key prefix fails during a download, the folder content is not rolled back to its state prior to the failure. The destination folder remains as it was at the time of the failure.

Supported use cases

The S3Download action module supports the following use cases:

IAM requirements

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

Input example: copy an Amazon S3 object to a local file

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

  - name: DownloadMyFile
    action: S3Download
    inputs:
      - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
        destination: C:\myfolder\package.zip
        expectedBucketOwner: 123456789022
        overwrite: false
      - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
        destination: C:\myfolder\package.zip
        expectedBucketOwner: 123456789022
        overwrite: true
      - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
        destination: C:\myfolder\package.zip
        expectedBucketOwner: 123456789022

Input example: copy all Amazon S3 objects in an Amazon S3 bucket with key prefix to a local folder

The following example shows how to copy all Amazon S3 objects in an Amazon S3 bucket with the key prefix to a local folder. Amazon S3 has no concept of a folder, therefore all objects that match the key prefix are copied. The maximum number of objects that can be downloaded is 1000.

  - name: MyS3DownloadKeyprefix
    action: S3Download
    maxAttempts: 3
    inputs:
      - source: s3://amzn-s3-demo-source-bucket/path/to/*
        destination: C:\myfolder\
        expectedBucketOwner: 123456789022
        overwrite: false
      - source: s3://amzn-s3-demo-source-bucket/path/to/*
        destination: C:\myfolder\
        expectedBucketOwner: 123456789022
        overwrite: true
      - source: s3://amzn-s3-demo-source-bucket/path/to/*
        destination: C:\myfolder\
        expectedBucketOwner: 123456789022

Output

None.

S3Upload (Linux, Windows, macOS)

With the S3Upload action module, you can upload a file from a source file or folder to an Amazon S3 location. You can use a wildcard (*) in the path specified for your source location to upload all of the files whose path matches the wildcard pattern.

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

IAM requirements

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

Input example: copy a local file to an Amazon S3 object

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

  - name: MyS3UploadFile
    action: S3Upload
    onFailure: Abort
    maxAttempts: 3
    inputs:
      - source: C:\myfolder\package.zip
        destination: s3://amzn-s3-demo-destination-bucket/path/to/package.zip
        expectedBucketOwner: 123456789022

Input example: copy all files in a local folder to an Amazon S3 bucket with key prefix

The following example shows how to copy all files in the local folder to an Amazon S3 bucket with key prefix. This example does not copy sub-folders 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://amzn-s3-demo-destination-bucket/path/to/
        expectedBucketOwner: 123456789022

Input example: copy all files and folders recursively from a local folder to an Amazon S3 bucket

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

  - name: MyS3UploadFolder
    action: S3Upload
    onFailure: Abort
    maxAttempts: 3
    inputs:
      - source: C:\myfolder\*
        destination: s3://amzn-s3-demo-destination-bucket/path/to/
        recurse: true
        expectedBucketOwner: 123456789022

Output

None.

WebDownload (Linux, Windows, macOS)

The WebDownload action module allows you to download files and resources from a remote location over the HTTP/HTTPS protocol (HTTPS is recommended). There are no limits on the number or size of downloads. This module handles retry and exponential backoff logic.

Each download operation is allocated a maximum of 5 attempts to succeed according to user inputs. These attempts differ from those specified in the maxAttempts field of document steps, which are related to action module failures.

This action module implicitly handles redirects. All HTTP status codes, except for 200, result in an error.

Input example: download remote file to local destination

  - name: DownloadRemoteFile
    action: WebDownload
    maxAttempts: 3
    inputs:
      - source: https://testdomain/path/to/java14.zip
        destination: C:\testfolder\package.zip

Output:

{
	"destination": "C:\\testfolder\\package.zip"
}

Input example: download more than one remote file to more than one local destination

  - name: DownloadRemoteFiles
    action: WebDownload
    maxAttempts: 3
    inputs:
      - source: https://testdomain/path/to/java14.zip
        destination: /tmp/java14_renamed.zip
      - source: https://testdomain/path/to/java14.zip
        destination: /tmp/create_new_folder_and_add_java14_as_zip/

Output:

{
	"destination": "/tmp/create_new_folder/java14_renamed.zip\n/tmp/create_new_folder_and_add_java14_as_zip/java14.zip"
}

Input example: download one remote file without overwriting local destination, and download another remote file with file verification

  - name: DownloadRemoteMultipleProperties
    action: WebDownload
    maxAttempts: 3
    inputs:
      - source: https://testdomain/path/to/java14.zip
        destination: C:\create_new_folder\java14_renamed.zip
        overwrite: false
      - source: https://testdomain/path/to/java14.zip
        destination: C:\create_new_folder_and_add_java14_as_zip\
        checksum: ac68bbf921d953d1cfab916cb6120864
        algorithm: MD5
        overwrite: true

Output:

{
	"destination": "C:\\create_new_folder\\java14_renamed.zip\nC:\\create_new_folder_and_add_java14_as_zip\\java14.zip"
}

Input example: download remote file and ignore SSL certification validation

  - name: DownloadRemoteIgnoreValidation
    action: WebDownload
    maxAttempts: 3
    inputs:
      - source: https://www.bad-ssl.com/resource
        destination: /tmp/downloads/
        ignoreCertificateErrors: true

Output:

{
	"destination": "/tmp/downloads/resource"
}

File system operations modules

The following section contains details for action modules that perform file system operations.

AppendFile (Linux, Windows, macOS)

The AppendFile action module adds specified content to the preexisting content of a file.

If the file encoding value is different from the default encoding (utf-8) value, then you can specify the file encoding value by using the encoding option. By default, utf-16 and utf-32 are assumed to use little-endian encoding.

The action module returns an error when the following occurs:

Input example: append file without encoding (Linux)

  - name: AppendingFileWithOutEncodingLinux
    action: AppendFile
    inputs:
      - path: ./Sample.txt
        content: "The string to be appended to the file"

Input example: append file without encoding (Windows)

  - name: AppendingFileWithOutEncodingWindows
    action: AppendFile
    inputs:
      - path: C:\MyFolder\MyFile.txt
        content: "The string to be appended to the file"

Input example: append file with encoding (Linux)

  - name: AppendingFileWithEncodingLinux
    action: AppendFile
    inputs:
      - path: /FolderName/SampleFile.txt
        content: "The string to be appended to the file"
        encoding: UTF-32

Input example: append file with encoding (Windows)

  - name: AppendingFileWithEncodingWindows
    action: AppendFile
    inputs:
      - path: C:\MyFolderName\SampleFile.txt
        content: "The string to be appended to the file"
        encoding: UTF-32

Input example: append file with empty string (Linux)

  - name: AppendingEmptyStringLinux
    action: AppendFile
    inputs:
      - path: /FolderName/SampleFile.txt

Input example: append file with empty string (Windows)

  - name: AppendingEmptyStringWindows
    action: AppendFile
    inputs:
      - path: C:\MyFolderName\SampleFile.txt

Output

None.

CopyFile (Linux, Windows, macOS)

The CopyFile action module copies files from the specified source to the specified destination. By default, the module recursively creates the destination folder if it does not exist at runtime.

If a file with the specified name already exists in the specified folder, the action module, by default, overwrites the existing file. You can override this default behavior by setting the overwrite option to false. When the overwrite option is set to false, and there is already a file in the specified location with the specified name, the action module will return an error. This option works the same as the cp command in Linux, which overwrites by default.

The source file name can include a wildcard (*). Wildcard characters are accepted only after the last file path separator (/ or \). If wildcard characters are included in the source file name, all of the files that match the wildcard are copied to the destination folder. If you want to move more than one file by using a wildcard character, the input to the destination option must end with a file path separator (/ or \), which indicates that the destination input is a folder.

If the destination file name is different from the source file name, you can specify the destination file name using the destination option. If you do not specify a destination file name, the name of the source file is used to create the destination file. Any text that follows the last file path separator (/ or \) is treated as the file name. If you want to use the same file name as the source file, then the input of the destination option must end with a file path separator (/ or \).

The action module returns an error when the following occurs:

Input example: copy a file (Linux)

  - name: CopyingAFileLinux
    action: CopyFile
    inputs:
      - source: /Sample/MyFolder/Sample.txt
        destination: /MyFolder/destinationFile.txt

Input example: copy a file (Windows)

  - name: CopyingAFileWindows
    action: CopyFile
    inputs:
      - source: C:\MyFolder\Sample.txt
        destination: C:\MyFolder\destinationFile.txt

Input example: copy a file using the source file name (Linux)

  - name: CopyingFileWithSourceFileNameLinux
    action: CopyFile
    inputs:
      - source: /Sample/MyFolder/Sample.txt
        destination: /MyFolder/

Input example: copy a file using the source file name (Windows)

  - name: CopyingFileWithSourceFileNameWindows
    action: CopyFile
    inputs:
      - source: C:\Sample\MyFolder\Sample.txt
        destination: C:\MyFolder\

Input example: copy a file using the wildcard character (Linux)

  - name: CopyingFilesWithWildCardLinux
    action: CopyFile
    inputs:
      - source: /Sample/MyFolder/Sample*
        destination: /MyFolder/

Input example: copy a file using the wildcard character (Windows)

  - name: CopyingFilesWithWildCardWindows
    action: CopyFile
    inputs:
      - source: C:\Sample\MyFolder\Sample*
        destination: C:\MyFolder\

Input example: copy a file without overwriting (Linux)

  - name: CopyingFilesWithoutOverwriteLinux
    action: CopyFile
    inputs:
      - source: /Sample/MyFolder/Sample.txt
        destination: /MyFolder/destinationFile.txt
        overwrite: false

Input example: copy a file without overwriting (Windows)

  - name: CopyingFilesWithoutOverwriteWindows
    action: CopyFile
    inputs:
      - source: C:\Sample\MyFolder\Sample.txt
        destination: C:\MyFolder\destinationFile.txt
        overwrite: false

Output

None.

CopyFolder (Linux, Windows, macOS)

The CopyFolder action module copies a folder from the specified source to the specified destination. The input for the source option is the folder to copy, and the input for the destination option is the folder where the contents of the source folder are copied. By default, the module recursively creates the destination folder if it does not exist at runtime.

If a folder with the specified name already exists in the specified folder, the action module, by default, overwrites the existing folder. You can override this default behavior by setting the overwrite option to false. When the overwrite option is set to false, and there is already a folder in the specified location with the specified name, the action module will return an error.

The source folder name can include a wildcard (*). Wildcard characters are accepted only after the last file path separator (/ or \). If wildcard characters are included in the source folder name, all of the folders that match the wildcard are copied to the destination folder. If you want to copy more than one folder by using a wildcard character, the input to the destination option must end with a file path separator (/ or \), which indicates that the destination input is a folder.

If the destination folder name is different from the source folder name, you can specify the destination folder name using the destination option. If you do not specify a destination folder name, the name of the source folder is used to create the destination folder. Any text that follows the last file path separator (/ or \) is treated as the folder name. If you want to use the same folder name as the source folder, then the input of the destination option must end with a file path separator (/ or \).

The action module returns an error when the following occurs:

Input example: copy a folder (Linux)

  - name: CopyingAFolderLinux
    action: CopyFolder
    inputs:
      - source: /Sample/MyFolder/SampleFolder
        destination: /MyFolder/destinationFolder

Input example: copy a folder (Windows)

  - name: CopyingAFolderWindows
    action: CopyFolder
    inputs:
      - source: C:\Sample\MyFolder\SampleFolder
        destination: C:\MyFolder\destinationFolder

Input example: copy a folder using the source folder name (Linux)

  - name: CopyingFolderSourceFolderNameLinux
    action: CopyFolder
    inputs:
      - source: /Sample/MyFolder/SourceFolder
        destination: /MyFolder/

Input example: copy a folder using the source folder name (Windows)

  - name: CopyingFolderSourceFolderNameWindows
    action: CopyFolder
    inputs:
      - source: C:\Sample\MyFolder\SampleFolder
        destination: C:\MyFolder\

Input example: copy a folder using the wildcard character (Linux)

  - name: CopyingFoldersWithWildCardLinux
    action: CopyFolder
    inputs:
      - source: /Sample/MyFolder/Sample*
        destination: /MyFolder/

Input example: copy a folder using the wildcard character (Windows)

  - name: CopyingFoldersWithWildCardWindows
    action: CopyFolder
    inputs:
      - source: C:\Sample\MyFolder\Sample*
        destination: C:\MyFolder\

Input example: copy a folder without overwriting (Linux)

  - name: CopyingFoldersWithoutOverwriteLinux
    action: CopyFolder
    inputs:
      - source: /Sample/MyFolder/SourceFolder
        destination: /MyFolder/destinationFolder
        overwrite: false

Input example: copy a folder without overwriting (Windows)

  - name: CopyingFoldersWithoutOverwrite
    action: CopyFolder
    inputs:
      - source: C:\Sample\MyFolder\SourceFolder
        destination: C:\MyFolder\destinationFolder
        overwrite: false

Output

None.

CreateFile (Linux, Windows, macOS)

The CreateFile action module creates a file in a specified location. By default, if required, the module also recursively creates the parent folders.

If the file already exists in the specified folder, the action module, by default, truncates or overwrites the existing file. You can override this default behavior by setting the overwrite option to false. When the overwrite option is set to false, and there is already a file in the specified location with the specified name, the action module will return an error.

If the file encoding value is different from the default encoding (utf-8) value, then you can specify the file encoding value by using the encoding option. By default, utf-16 and utf-32 are assumed to use little-endian encoding.

owner, group, and permissions are optional inputs. The input for permissions must be a string value. Files are created with default values when not provided. These options are not supported on Windows platforms. This action module validates and returns an error if the owner, group, and permissions options are used on Windows platforms.

This action module can create a file the with permissions defined by the default umask value of the operating system. You must set the umask value if you want to override the default value.

The action module returns an error when the following occurs:

Input example: create a file without overwriting (Linux)

  - name: CreatingFileWithoutOverwriteLinux
    action: CreateFile
    inputs:
      - path: /home/UserName/Sample.txt
        content: The text content of the sample file.
        overwrite: false

Input example: create a file without overwriting (Windows)

  - name: CreatingFileWithoutOverwriteWindows
    action: CreateFile
    inputs:
      - path: C:\Temp\Sample.txt
        content: The text content of the sample file.
        overwrite: false

Input example: create a file with file properties

  - name: CreatingFileWithFileProperties
    action: CreateFile
    inputs:
      - path: SampleFolder/Sample.txt
        content: The text content of the sample file.
        encoding: UTF-16
        owner: Ubuntu
        group: UbuntuGroup
        permissions: 0777
     - path: SampleFolder/SampleFile.txt
        permissions: 755
      - path: SampleFolder/TextFile.txt
        encoding: UTF-16
        owner: root
        group: rootUserGroup

Input example: create a file without file properties

  - name: CreatingFileWithoutFileProperties
    action: CreateFile
    inputs:
      - path: ./Sample.txt
      - path: Sample1.txt

Input example: create an empty file to skip a section in the Linux clean up script

  - name: CreateSkipCleanupfile
    action: CreateFile
    inputs:
      - path: <skip section file name>

For more information, see Override the Linux clean up script

Output

None.

CreateFolder (Linux, Windows, macOS)

The CreateFolder action module creates a folder in a specified location. By default, if required, the module also recursively creates the parent folders.

If the folder already exists in the specified folder, the action module, by default, truncates or overwrites the existing folder. You can override this default behavior by setting the overwrite option to false. When the overwrite option is set to false, and there is already a folder in the specified location with the specified name, the action module will return an error.

owner, group, and permissions are optional inputs. The input for permissions must be a string value. These options are not supported on Windows platforms. This action module validates and returns an error if the owner, group, and permissions options are used on Windows platforms.

This action module can create a folder the with permissions defined by the default umask value of the operating system. You must set the umask value if you want to override the default value.

The action module returns an error when the following occurs:

Input example: create a folder (Linux)

  - name: CreatingFolderLinux
    action: CreateFolder
    inputs:
      - path: /Sample/MyFolder/

Input example: create a folder (Windows)

  - name: CreatingFolderWindows
    action: CreateFolder
    inputs:
      - path: C:\MyFolder

Input example: create a folder specifying folder properties

  - name: CreatingFolderWithFolderProperties
    action: CreateFolder
    inputs:
      - path: /Sample/MyFolder/Sample/
        owner: SampleOwnerName
        group: SampleGroupName
        permissions: 0777
      - path: /Sample/MyFolder/SampleFoler/
        permissions: 777

Input example: create a folder that overwrites the existing folder, if there is one.

  - name: CreatingFolderWithOverwrite
    action: CreateFolder
    inputs:
      - path: /Sample/MyFolder/Sample/
        overwrite: true

Output

None.

CreateSymlink (Linux, Windows, macOS)

The CreateSymlink action module creates symbolic links, or files that contain a reference to another file. This module is not supported on Windows platforms.

The input for the path and target options can be either an absolute or relative path. If the input for the path option is a relative path, it is replaced with the absolute path when the link is created.

By default, when a link with the specified name already exists in the specified folder, the action module returns an error. You can override this default behavior by setting the force option to true. When the force option is set to true, the module will overwrite the existing link.

If a parent folder does not exist, the action module creates the folder recursively, by default.

The action module returns an error when the following occurs:

Input example: create symbolic link that forces the creation of a link

  - name: CreatingSymbolicLinkWithForce
    action: CreateSymlink
    inputs:
      - path: /Folder2/Symboliclink.txt
        target: /Folder/Sample.txt
        force: true

Input example: create a symbolic link that does not force the creation of a link

  - name: CreatingSymbolicLinkWithOutForce
    action: CreateSymlink
    inputs:
      - path: Symboliclink.txt
        target: /Folder/Sample.txt

Output

None.

DeleteFile (Linux, Windows, macOS)

The DeleteFile action module deletes a file or files in a specified location.

The input of path should be a valid file path or a file path with a wild card character (*) in the file name. When wildcard characters are specified in the file name, all of the files within the same folder that match the wildcard will be deleted.

The action module returns an error when the following occurs:

Input example: delete a single file (Linux)

  - name: DeletingSingleFileLinux
    action: DeleteFile
    inputs:
      - path: /SampleFolder/MyFolder/Sample.txt

Input example: delete a single file (Windows)

  - name: DeletingSingleFileWindows
    action: DeleteFile
    inputs:
      - path: C:\SampleFolder\MyFolder\Sample.txt

Input example: delete a file that ends with "log" (Linux)

  - name: DeletingFileEndingWithLogLinux
    action: DeleteFile
    inputs:
      - path: /SampleFolder/MyFolder/*log

Input example: delete a file that ends with "log" (Windows)

  - name: DeletingFileEndingWithLogWindows
    action: DeleteFile
    inputs:
      - path: C:\SampleFolder\MyFolder\*log

Input example: delete all files in a specified folder (Linux)

  - name: DeletingAllFilesInAFolderLinux
    action: DeleteFile
    inputs:
      - path: /SampleFolder/MyFolder/*

Input example: delete all files in a specified folder (Windows)

  - name: DeletingAllFilesInAFolderWindows
    action: DeleteFile
    inputs:
      - path: C:\SampleFolder\MyFolder\*

Output

None.

DeleteFolder (Linux, Windows, macOS)

The DeleteFolder action module deletes folders.

If the folder is not empty, you must set the force option to true to remove the folder and its contents. If you do not set the force option to true, and the folder you are trying to delete is not empty, the action module returns an error. The default value of the force option is false.

The action module returns an error when the following occurs:

Input example: delete a folder that is not empty using the force option (Linux)

  - name: DeletingFolderWithForceOptionLinux
    action: DeleteFolder
    inputs:
      - path: /Sample/MyFolder/Sample/
        force: true

Input example: delete a folder that is not empty using the force option (Windows)

  - name: DeletingFolderWithForceOptionWindows
    action: DeleteFolder
    inputs:
      - path: C:\Sample\MyFolder\Sample\
        force: true

Input example: delete a folder (Linux)

  - name: DeletingFolderWithOutForceLinux
    action: DeleteFolder
    inputs:
      - path: /Sample/MyFolder/Sample/

Input example: delete a folder (Windows)

  - name: DeletingFolderWithOutForce
    action: DeleteFolder
    inputs:
      - path: C:\Sample\MyFolder\Sample\

Output

None.

ListFiles (Linux, Windows, macOS)

The ListFiles action module lists the files in a specified folder. When the recursive option is set to true, it lists the files in subfolders. This module does not list files in subfolders by default.

To list all of the files with names that match a specified pattern, use the fileNamePattern option to provide the pattern. The fileNamePattern option accepts the wildcard (*) value. When the fileNamePattern is provided, all of the files that match the specified file name format are returned.

The action module returns an error when the following occurs:

Input example: list files in specified folder (Linux)

  - name: ListingFilesInSampleFolderLinux
    action: ListFiles
    inputs:
      - path: /Sample/MyFolder/Sample

Input example: list files in specified folder (Windows)

  - name: ListingFilesInSampleFolderWindows
    action: ListFiles
    inputs:
      - path: C:\Sample\MyFolder\Sample

Input example: list files that end with "log" (Linux)

  - name: ListingFilesWithEndingWithLogLinux
    action: ListFiles
    inputs:
      - path: /Sample/MyFolder/
        fileNamePattern: *log

Input example: list files that end with "log" (Windows)

  - name: ListingFilesWithEndingWithLogWindows
    action: ListFiles
    inputs:
      - path: C:\Sample\MyFolder\
        fileNamePattern: *log

Input example: list files recursively

  - name: ListingFilesRecursively
    action: ListFiles
    inputs:
      - path: /Sample/MyFolder/
        recursive: true

Output example

{
	"files": "/sample1.txt,/sample2.txt,/sample3.txt"
}

MoveFile (Linux, Windows, macOS)

The MoveFile action module moves files from the specified source to the specified destination.

If the file already exists in the specified folder, the action module, by default, overwrites the existing file. You can override this default behavior by setting the overwrite option to false. When the overwrite option is set to false, and there is already a file in the specified location with the specified name, the action module will return an error. This option works the same as the mv command in Linux, which overwrites by default.

The source file name can include a wildcard (*). Wildcard characters are accepted only after the last file path separator (/ or \). If wildcard characters are included in the source file name, all of the files that match the wildcard are copied to the destination folder. If you want to move more than one file by using a wildcard character, the input to the destination option must end with a file path separator (/ or \), which indicates that the destination input is a folder.

If the destination file name is different from the source file name, you can specify the destination file name using the destination option. If you do not specify a destination file name, the name of the source file is used to create the destination file. Any text that follows the last file path separator (/ or \) is treated as the file name. If you want to use the same file name as the source file, then the input of the destination option must end with a file path separator (/ or \).

The action module returns an error when the following occurs:

Input example: move a file (Linux)

  - name: MovingAFileLinux
    action: MoveFile
    inputs:
      - source: /Sample/MyFolder/Sample.txt
        destination: /MyFolder/destinationFile.txt

Input example: move a file (Windows)

  - name: MovingAFileWindows
    action: MoveFile
    inputs:
      - source: C:\Sample\MyFolder\Sample.txt
        destination: C:\MyFolder\destinationFile.txt

Input example: move a file using the source file name (Linux)

  - name: MovingFileWithSourceFileNameLinux
    action: MoveFile
    inputs:
      - source: /Sample/MyFolder/Sample.txt
        destination: /MyFolder/

Input example: move a file using the source file name (Windows)

  - name: MovingFileWithSourceFileNameWindows
    action: MoveFile
    inputs:
      - source: C:\Sample\MyFolder\Sample.txt
        destination: C:\MyFolder

Input example: move a file using a wildcard character (Linux)

  - name: MovingFilesWithWildCardLinux
    action: MoveFile
    inputs:
      - source: /Sample/MyFolder/Sample*
        destination: /MyFolder/

Input example: move a file using a wildcard character (Windows)

  - name: MovingFilesWithWildCardWindows
    action: MoveFile
    inputs:
      - source: C:\Sample\MyFolder\Sample*
        destination: C:\MyFolder

Input example: move a file without overwriting (Linux)

  - name: MovingFilesWithoutOverwriteLinux
    action: MoveFile
    inputs:
      - source: /Sample/MyFolder/Sample.txt
        destination: /MyFolder/destinationFile.txt
        overwrite: false

Input example: move a file without overwriting (Windows)

  - name: MovingFilesWithoutOverwrite
    action: MoveFile
    inputs:
      - source: C:\Sample\MyFolder\Sample.txt
        destination: C:\MyFolder\destinationFile.txt
        overwrite: false

Output

None.

MoveFolder (Linux, Windows, macOS)

The MoveFolder action module moves folders from the specified source to the specified destination. The input for the source option is the folder to move, and the input to the destination option is the folder where the contents of the source folders are moved.

If the destination parent folder or the input to the destination option does not exist at runtime, the default behavior of the module is to recursively create the folder at the specified destination.

If a folder with the same as the source folder already exists in the destination folder, the action module, by default, overwrites the existing folder. You can override this default behavior by setting the overwrite option to false. When the overwrite option is set to false, and there is already a folder in the specified location with the specified name, the action module will return an error.

The source folder name can include a wildcard (*). Wildcard characters are accepted only after the last file path separator (/ or \). If wildcard characters are included in the source folder name, all of the folders that match the wildcard are copied to the destination folder. If you want to move more than one folder by using a wildcard character, the input to the destination option must end with a file path separator (/ or \), which indicates that the destination input is a folder.

If the destination folder name is different from the source folder name, you can specify the destination folder name using the destination option. If you do not specify a destination folder name, the name of the source folder is used to create the destination folder. Any text that follows the last file path separator (/ or \) is treated as the folder name. If you want to use the same folder name as the source folder, then the input of the destination option must end with a file path separator (/ or \).

The action module returns an error when the following occurs:

Input example: move a folder (Linux)

  - name: MovingAFolderLinux
    action: MoveFolder
    inputs:
      - source: /Sample/MyFolder/SourceFolder
        destination: /MyFolder/destinationFolder

Input example: move a folder (Windows)

  - name: MovingAFolderWindows
    action: MoveFolder
    inputs:
      - source: C:\Sample\MyFolder\SourceFolder
        destination: C:\MyFolder\destinationFolder

Input example: move a folder using the source folder name (Linux)

  - name: MovingFolderWithSourceFolderNameLinux
    action: MoveFolder
    inputs:
      - source: /Sample/MyFolder/SampleFolder
        destination: /MyFolder/

Input example: move a folder using the source folder name (Windows)

  - name: MovingFolderWithSourceFolderNameWindows
    action: MoveFolder
    inputs:
      - source: C:\Sample\MyFolder\SampleFolder
        destination: C:\MyFolder\

Input example: move a folder using a wildcard character (Linux)

  - name: MovingFoldersWithWildCardLinux
    action: MoveFolder
    inputs:
      - source: /Sample/MyFolder/Sample*
        destination: /MyFolder/

Input example: move a folder using a wildcard character (Windows)

  - name: MovingFoldersWithWildCardWindows
    action: MoveFolder
    inputs:
      - source: C:\Sample\MyFolder\Sample*
        destination: C:\MyFolder\

Input example: move a folder without overwriting (Linux)

  - name: MovingFoldersWithoutOverwriteLinux
    action: MoveFolder
    inputs:
      - source: /Sample/MyFolder/SampleFolder
    destination: /MyFolder/destinationFolder
    overwrite: false

Input example: move a folder without overwriting (Windows)

  - name: MovingFoldersWithoutOverwriteWindows
    action: MoveFolder
    inputs:
      - source: C:\Sample\MyFolder\SampleFolder
        destination: C:\MyFolder\destinationFolder
        overwrite: false

Output

None.

ReadFile (Linux, Windows, macOS)

The ReadFile action module reads the content of a text file of type string. This module can be used to read the content of a file for use in subsequent steps through chaining or for reading data to the console.log file. If the specified path is a symbolic link, this module returns the content of the target file. This module only supports text files.

If the file encoding value is different from the default encoding (utf-8) value, then you can specify the file encoding value by using the encoding option. By default, utf-16 and utf-32 are assumed to use little-endian encoding.

By default, this module cannot print the file content to the console.log file. You can override this setting by setting the printFileContent property to true.

This module can return only the content of a file. It cannot parse files, such as Excel or JSON files.

The action module returns an error when the following occurs:

Input example: read a file (Linux)

  - name: ReadingFileLinux
    action: ReadFile
    inputs:
      - path: /home/UserName/SampleFile.txt

Input example: read a file (Windows)

  - name: ReadingFileWindows
    action: ReadFile
    inputs:
      - path: C:\Windows\WindowsUpdate.log

Input example: read a file and specify encoding standard

  - name: ReadingFileWithFileEncoding
    action: ReadFile
    inputs:
      - path: /FolderName/SampleFile.txt
        encoding: UTF-32

Input example: read a file and print to the console.log file

  - name: ReadingFileToConsole
    action: ReadFile
    inputs:
      - path: /home/UserName/SampleFile.txt
        printFileContent: true

Output example

{
	"content" : "The file content"
}

SetFileEncoding (Linux, Windows, macOS)

The SetFileEncoding action module modifies the encoding property of an existing file. This module can convert file encoding from utf-8 to a specified encoding standard. By default, utf-16 and utf-32 are assumed to be little-endian encoding.

The action module returns an error when the following occurs:

Input example: set file encoding property

  - name: SettingFileEncodingProperty
    action: SetFileEncoding
    inputs:
      - path: /home/UserName/SampleFile.txt
        encoding: UTF-16

Output

None.

SetFileOwner (Linux, Windows, macOS)

The SetFileOwner action module modifies the owner andgroup owner properties of an existing file. If the specified file is a symbolic link, the module modifies the owner property of the source file. This module is not supported on Windows platforms.

This module accepts user and group names as inputs. If the group name is not provided, the module assigns the group owner of the file to the group that the user belongs to.

The action module returns an error when the following occurs:

Input example: set file owner property without specifying the name of the user group

  - name: SettingFileOwnerPropertyNoGroup
    action: SetFileOwner
    inputs:
      - path: /home/UserName/SampleText.txt
        owner: LinuxUser

Input example: set file owner property by specifying the owner and the user group

  - name: SettingFileOwnerProperty
    action: SetFileOwner
    inputs:
      - path: /home/UserName/SampleText.txt
        owner: LinuxUser
        group: LinuxUserGroup

Output

None.

SetFolderOwner (Linux, Windows, macOS)

The SetFolderOwner action module recursively modifies the owner andgroup owner properties of an existing folder. By default, the module can modify ownership for all of the contents in a folder. You can set the recursive option to false to override this behavior. This module is not supported on Windows platforms.

This module accepts user and group names as inputs. If the group name is not provided, the module assigns the group owner of the file to the group that the user belongs to.

The action module returns an error when the following occurs:

Input example: set folder owner property without specifying the name of the user group

  - name: SettingFolderPropertyWithOutGroup
    action: SetFolderOwner
    inputs:
      - path: /SampleFolder/
        owner: LinuxUser

Input example: set folder owner property without overriding the ownership of all of the contents in a folder

  - name: SettingFolderPropertyWithOutRecursively
    action: SetFolderOwner
    inputs:
      - path: /SampleFolder/
        owner: LinuxUser
        recursive: false

Input example: set file ownership property by specifying the name of the user group

  - name: SettingFolderPropertyWithGroup
    action: SetFolderOwner
    inputs:
      - path: /SampleFolder/
        owner: LinuxUser
        group: LinuxUserGroup

Output

None.

SetFilePermissions (Linux, Windows, macOS)

The SetFilePermissions action module modifies the permissions of an existing file. This module is not supported on Windows platforms.

The input for permissions must be a string value.

This action module can create a file the with permissions defined by the default umask value of the operating system. You must set the umask value if you want to override the default value.

The action module returns an error when the following occurs:

Input example: modify file permissions

  - name: ModifyingFilePermissions
    action: SetFilePermissions
    inputs:
      - path: /home/UserName/SampleFile.txt
        permissions: 766

Output

None.

SetFolderPermissions (Linux, Windows, macOS)

The SetFolderPermissions action module recursively modifies the permissions of an existing folder and all of its subfiles and subfolders. By default, this module can modify permissions for all of the contents of the specified folder. You can set the recursive option to false to override this behavior. This module is not supported on Windows platforms.

The input for permissions must be a string value.

This action module can modify permissions according to the default umask value of the operating system. You must set the umask value if you want to override the default value.

The action module returns an error when the following occurs:

Input example: set folder permissions

  - name: SettingFolderPermissions
    action: SetFolderPermissions
    inputs:
      - path: SampleFolder/
        permissions: 0777

Input example: set folder permissions without modifying permissions for all of the contents of a folder

  - name: SettingFolderPermissionsNoRecursive
    action: SetFolderPermissions
    inputs:
      - path: /home/UserName/SampleFolder/
        permissions: 777
        recursive: false

Output

None.

Software installation actions

The following section describes action modules that install or uninstall software.

IAM requirements

If your installation download path is an S3 URI, then the IAM role that you associate with your instance profile must have permission to run the S3Download action module. To grant the required permission, attach the S3:GetObject IAM policy to the IAM role that is associated with your instance profile, and specify the path for your bucket. For example, arn:aws:s3:::BucketName/*).

Complex MSI Inputs

If your input strings contain double quote characters ("), you must use one of the following methods to ensure that they are interpreted correctly:

Both of these methods pass the value COMPANYNAME="Acme ""Widgets"" and ""Gizmos.""" to the msiexec command.

InstallMSI (Windows)

The InstallMSI action module installs a Windows application using an MSI file. You can specify the MSI file using a local path, an S3 object URI, or a web URL. The reboot option configures the reboot behavior of the system.

AWSTOE generates the msiexec command based on the input parameters for the action module. Values for the path (MSI file location) and logFile (log file location) input parameters must be enclosed in quotation marks (").

The following MSI exit codes are considered successful:

Examples

The following examples show variations of the input section for your component document, depending on your installation path.

Input example: local document path installation

- name: local-path-install
  steps:
    - name: LocalPathInstaller
      action: InstallMSI
      inputs:
        path: C:\sample.msi
        logFile: C:\msilogs\local-path-install.log
        logOptions: '*VX'
        reboot: Allow
        properties:
          COMPANYNAME: '"Amazon Web Services"'
        ignoreAuthenticodeSignatureErrors: true
        allowUnsignedInstaller: true

Input example: Amazon S3 path installation

- name: s3-path-install
  steps:
    - name: S3PathInstaller
      action: InstallMSI
      inputs:
        path: s3://<bucket-name>/sample.msi
        logFile: s3-path-install.log
        reboot: Force
        ignoreAuthenticodeSignatureErrors: false
        allowUnsignedInstaller: true

Input example: web path installation

- name: web-path-install
  steps:
    - name: WebPathInstaller
      action: InstallMSI
      inputs:
        path: https://<some-path>/sample.msi
        logFile: web-path-install.log
        reboot: Skip
        ignoreAuthenticodeSignatureErrors: true
        allowUnsignedInstaller: false

Output

The following is an example of the output from the InstallMSI action module.

{
	"logFile": "web-path-install.log",
	"msiExitCode": 0,
	"stdout": ""
}

UninstallMSI (Windows)

The UninstallMSI action module allows you to remove a Windows application using an MSI file. You can specify the MSI file location using a local file path, an S3 object URI, or a web URL. The reboot option configures the reboot behavior of the system.

AWSTOE generates the msiexec command based on the input parameters for the action module. The MSI file location (path) and log file location (logFile) are explicitly enclosed in double quotes (") while generating the msiexec command.

The following MSI exit codes are considered successful:

Examples

The following examples show variations of the input section for your component document, depending on your installation path.

Input example: remove local document path installation

- name: local-path-uninstall
  steps:
    - name: LocalPathUninstaller
      action: UninstallMSI
      inputs:
        path: C:\sample.msi
        logFile: C:\msilogs\local-path-uninstall.log
        logOptions: '*VX'
        reboot: Allow
        properties:
          COMPANYNAME: '"Amazon Web Services"'
        ignoreAuthenticodeSignatureErrors: true
        allowUnsignedInstaller: true

Input example: remove Amazon S3 path installation

- name: s3-path-uninstall
  steps:
    - name: S3PathUninstaller
      action: UninstallMSI
      inputs:
        path: s3://<bucket-name>/sample.msi
        logFile: s3-path-uninstall.log
        reboot: Force
        ignoreAuthenticodeSignatureErrors: false
        allowUnsignedInstaller: true

Input example: remove web path installation

- name: web-path-uninstall
  steps:
    - name: WebPathUninstaller
      action: UninstallMSI
      inputs:
        path: https://<some-path>/sample.msi
        logFile: web-path-uninstall.log
        reboot: Skip
        ignoreAuthenticodeSignatureErrors: true
        allowUnsignedInstaller: false

Output

The following is an example of the output from the UninstallMSI action module.

{
	"logFile": "web-path-uninstall.log",
	"msiExitCode": 0,
	"stdout": ""
}

System action modules

The following section describes action modules that perform system actions or update system settings.

Reboot (Linux, Windows)

The Reboot action module reboots the instance. It has a configurable option to delay the start of the reboot. By default, delaySeconds is set to 0, which means that there is no delay. Step timeout is not supported for the Reboot action module, as it does not apply when the instance is rebooted.

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

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

Post-reboot auto-run trigger:

@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 example: reboot step

  - 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.

SetRegistry (Windows)

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 example: set registry key values

  - 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.

UpdateOS (Linux, Windows)

The UpdateOS action module adds support for installing Windows and Linux updates. It installs all available updates by default. Alternatively, you can configure a list of one or more specific updates for the action module to install. You can also specify updates to exclude from the installation.

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.

Input example: add support for installing Linux updates

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

Input example: add support for installing Windows updates

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

Output

None.