Use documents in EC2 Image Builder - EC2 Image Builder

Use documents in EC2 Image Builder

To build a component, you must provide a YAML-based document, which represents the phases and steps to create the component.

Document sections

The sections of a document are as follows.

  • Phases. Phases are a logical grouping of steps.

    • Each phase name must be unique within a document.

    • You can define many phases in a document.

    • Image Builder runs phases called build, validate, and test in the image build pipeline.

  • Steps. Steps are individual units of work that comprise the workflow for each phase.

    • Each step must define the action to take.

    • Each step must have a unique name per phase.

    • Steps are run sequentially.

    • Both the input and output of a step can be used as inputs for a subsequent step. This is called “chaining”.

    • Each step uses an action module that returns an exit code.

  • Supported actions. Supported actions must be contained for each step in a document. Each supported action correlates to an action module. For a complete list of supported action modules, how they work, input/output values, and examples, see Component manager supported action modules.

  • Output files. The configuration management application creates the following output files each time the application is run:

    • detailedOutput.json: A file that describes all of the detailed information about the orchestration. Contains information about each phase, step, and the action that occurs when the application is run.

    • document.yaml: The file that is sent to the application to be run. After the application runs, this file is stored as an artifact.

    • console.log: Contains all of the standard out (stdout) and standard error (stderr) information captured while the application is running.

    • application.log: Contains the logs generated by debugging instances.

Input and output chaining

The configuration management application provides a feature for chaining inputs and outputs by writing references in the following formats:

{{ phase_name.step_name.inputs/outputs.variable }}

or

{{ phase_name.step_name.inputs/outputs[index].variable }}

The chaining feature allows you to recycle code and improve the maintainability of the document.

The usage requirements of chaining are as follows:

  • Chaining expressions can be used only in the inputs section of each step.

  • Statements with chaining expressions must be enclosed in quotes. For example:

    • Invalid expression: echo {{ phase.step.inputs.variable }}

    • Valid expression: "echo {{ phase.step.inputs.variable }}"

    • Valid expression: 'echo {{ phase.step.inputs.variable }}'

  • Chaining expressions can reference variables from other steps and phases in the same document.

  • Indexes in chaining expressions follow 0-based indexing (first index is 0).

Examples

To refer to the source variable in the second entry of the following example step, the chaining pattern is {{ build.SampleS3Download.inputs[1].source }}.

phases: - name: 'build' steps: - name: SampleS3Download action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://sample-bucket/sample1.ps1' destination: 'C:\Temp\sample1.ps1' - source: 's3://sample-bucket/sample2.ps1' destination: 'C:\Temp\sample2.ps1'

To refer to the output variable (equal to "Hello") of the following example step, the chaining pattern is {{ build.SamplePowerShellStep.outputs.stdout }}.

phases: - name: 'build' steps: - name: SamplePowerShellStep action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'echo "Hello"'

Document schema and definitions

The following is the YAML schema for a document.

name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue" maxAttempts: integer inputs:

The schema definitions for a document are as follows.

Field Description Type Required
name Name of the document. String No
description Description of the document. String

No

schemaVersion Schema version of the document, currently 1.0. String

Yes

phases A list of phases with their steps.

List

Yes

The schema definitions for a phase are as follows.

Field Description Type Required
name Name of the phase. String Yes
steps List of the steps in the phase. List

Yes

The schema definitions for a step are as follows.

Field Description Type Required Default value
name User-defined name for the step. String
action Keyword pertaining to the module that runs the step. String
timeoutSeconds

Number of seconds that the step runs before failing or retrying.

Also, supports -1 value, which indicates infinite timeout. 0 and other negative values are not allowed.

Integer

Yes

7,200 sec (120 mins)
onFailure Specifies what the step should do in case of failure: abort or continue to the next step.

String

Yes

Abort
maxAttempts Maximum number of attempts allowed before failing the step. Integer

No

1
inputs Contains parameters required by the action module to run the step. Dict

Yes

Document example schemas

The following is an example document schema to install all available Windows updates, run a configuration script, validate the changes before the AMI is created, and test the changes after the AMI is created.

name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and execute a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\Temp\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Remove-Item {{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\Temp\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Remove-Item {{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\Temp\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - '{{test.DownloadTestConfigScript.inputs[0].destination}}'

The following is an example document schema to download and run a custom Linux binary file.

name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://mybucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: ExecuteBash inputs: commands: - 'rm {{ build.Download.inputs[0].destination }}'

The following is an example document schema to install the AWS CLI using the setup file.

name: InstallCLISetUp description: Install AWS CLI using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: ExecutePowerShell inputs: commands: - Remove-Item -Path '{{ build.Download.inputs[0].destination }}' -Force

The following is an example document schema to install the AWS CLI using the MSI installer.

name: InstallCLIMSI description: Install AWS CLI using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: ExecutePowerShell inputs: commands: - Remove-Item -Path '{{ build.Download.inputs[0].destination }}' -Force