This module allows you use file content from script files (Such as .ps1
or .sh
) and embed them inside Image Builder YAML documents.
This enables users to develop and test scripts using their favorite IDE's, Linters and Testing frameworks which is not possible when you are writing code directly in YAML documents.
This tool is developed in PowerShell to enable cross-platform support making it compatible with both Linux and Windows CI/CD pipelines. The goal of this module is to help accelerate the development of EC2 Image Builder components.
This module provides the following Functions and Aliases:
Function | Alias |
---|---|
New-ImageBuilderDocument | IBD, New-EC2IBDocument, IBDocument |
New-ImageBuilderPhase | IBP, New-EC2IBPhase, IBPhase |
New-ImageBuilderStep | IBS, New-EC2IBStep, IBStep |
New-ImageBuilderS3Action | IBS3A, New-EC2IBS3Action, IBS3Action |
New-ImageBuilderRegistryAction | IBRA, New-EC2IBRegAction, IBRegAction |
Below we will provide multiple options to generate the following EC2 Image Builder YAML document. The command for the second step is stored as install-sw.ps1
name: ExampleDoc
description: For Readme File
schemaVersion: '1.0'
phases:
- name: build
steps:
- name: HelloWorld
action: ExecutePowerShell
inputs:
commands:
- Write-Output "HelloWorld!"
- name: install-sw
action: ExecutePowerShell
inputs:
commands:
- |-
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
Install-Module PowerShellGet, PackageManagement -Force -SkipPublisherCheck -Scope CurrentUser -AllowClobber
$pkg = Install-PackageProvider -Name NuGet -Force
Write-Output "Installed NuGet version '$($pkg.version)'"
IBD 'ExampleDoc' -Description 'For Readme File' @(
IBP 'build' @(
(IBS 'HelloWorld' -pwsh 'Write-Output "HelloWorld!"'),
(IBS 'install-sw' -pwsh (Get-Content ./install-sw.ps1 -Raw))
)
)
$step1 = New-ImageBuilderStep 'HelloWorld' -ExecutePowerShell -Commands 'Write-Output "HelloWorld!"'
$step2 = New-ImageBuilderStep 'install-sw' -ExecutePowerShell -Commands (Get-Content ./install-sw.ps1 -Raw)
$phase1 = New-ImageBuilderPhase 'build' -steps $step1, $step2
New-ImageBuilderDocument -phases $phase1 -name 'ExampleDoc' -Description 'For Readme File'
(IBS 'HelloWorld' -pwsh 'Write-Output "HelloWorld!"'),
(IBS 'install-sw' -pwsh (Get-Content ./install-sw.ps1 -Raw))
| IBP 'build' | IBD 'ExampleDoc' -Description 'For Readme File'
A more complex fictional example to demonstrate available actions:
IBD 'ExampleDoc' -Description 'For Readme File' @(
IBP 'build' @(
IBS 'InstallDotnet' -ExecuteBinary -path 'C:\PathTo\dotnet_installer.exe' -arguments '/qb','/norestart','/silent'
IBS 'HelloWorld' -pwsh -commands 'Write-Output "HelloWorld!"'
IBS 'CreateLogsFolder' -sh 'mkdir logs' -onFailure 'Abort'
IBS 'Reboot' -Reboot -DelaySeconds 0
IBS 'AnotherReboot' -Reboot -maxAttempts 3
IBS 'DownloadFile' -S3Download -ImageBuilderS3Actions (ibs3a 'C:\myfolder\*' 's3://mybucket/path/to/' -recurse)
IBS 'RegAddVersion' -SetRegistry (ibra 'Version' '1.1' 'DWORD' 'HKCU:\Software\Test')
)
)
Would create:
name: ExampleDoc
description: For Readme File
schemaVersion: "1.0"
phases:
- name: build
steps:
- name: InstallDotnet
action: ExecuteBinary
inputs:
path: C:\PathTo\dotnet_installer.exe
arguments:
- /qb
- /norestart
- /silent
- name: HelloWorld
action: ExecutePowerShell
inputs:
commands:
- Write-Output "HelloWorld!"
- name: CreateLogsFolder
action: ExecuteBash
onFailure: Abort
inputs:
commands:
- mkdir logs
- name: Reboot
action: Reboot
inputs:
delaySeconds: 0
- name: AnotherReboot
action: Reboot
maxAttempts: 3
- name: DownloadFile
action: S3Download
inputs:
- source: C:\myfolder\*
destination: s3://mybucket/path/to/
recurse: true
- name: RegAddVersion
action: SetRegistry
inputs:
- path: HKCU:\Software\Test
name: Version
value: "1.1"
type: DWORD
You can validate whether these documents are considered valid in your CI/CD pipeline by leveraging TOE.
The TOE application allows you to validate whether a document is valid using the validate
command. For example, you can use it as follows on Windows:
(& 'C:\toe.exe' validate -d 'c:\document.yml' | ConvertFrom-json).validationStatus
This should return 'success' if your document is formatted correctly.
This library is licensed under the MIT-0 License. See the LICENSE file.