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.
Topics
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:SampleS3Downloadaction: 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:SamplePowerShellStepaction: 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/myapplicationdestination: /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
