https://github.com/awslabs/aws-image-builder-document-generator
EC2 Image Builder Component Document Generator. A PowerShell module to convert your Bash and PowerShell scripts into EC2 Image Builder Component Documents.
https://github.com/awslabs/aws-image-builder-document-generator
Last synced: 4 months ago
JSON representation
EC2 Image Builder Component Document Generator. A PowerShell module to convert your Bash and PowerShell scripts into EC2 Image Builder Component Documents.
- Host: GitHub
- URL: https://github.com/awslabs/aws-image-builder-document-generator
- Owner: awslabs
- License: mit-0
- Created: 2020-05-25T09:17:11.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2020-06-11T14:54:31.000Z (almost 5 years ago)
- Last Synced: 2024-05-23T00:34:14.181Z (11 months ago)
- Language: PowerShell
- Homepage:
- Size: 19.5 KB
- Stars: 12
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - awslabs/aws-image-builder-document-generator - EC2 Image Builder Component Document Generator. A PowerShell module to convert your Bash and PowerShell scripts into EC2 Image Builder Component Documents. (PowerShell)
README
# aws-image-builder-document-generator
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.
## Functions & Aliases
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 |
## Workflow
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`
```yaml
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)'"
```
### Option 1 - DSL Syntax
```PowerShell
IBD 'ExampleDoc' -Description 'For Readme File' @(
IBP 'build' @(
(IBS 'HelloWorld' -pwsh 'Write-Output "HelloWorld!"'),
(IBS 'install-sw' -pwsh (Get-Content ./install-sw.ps1 -Raw))
)
)
```
### Option 2 - Verbose PowerShell example
```PowerShell
$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'
```
### Option 3 - Using the pipeline
```PowerShell
(IBS 'HelloWorld' -pwsh 'Write-Output "HelloWorld!"'),
(IBS 'install-sw' -pwsh (Get-Content ./install-sw.ps1 -Raw))
| IBP 'build' | IBD 'ExampleDoc' -Description 'For Readme File'
```
## Available step actions
A more complex **fictional** example to demonstrate available **actions**:
```PowerShell
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:
```YAML
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
```
## Validating the whether documents are formatted correctly
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:
```powershell
(& 'C:\toe.exe' validate -d 'c:\document.yml' | ConvertFrom-json).validationStatus
```
This should return 'success' if your document is formatted correctly.
## License
This library is licensed under the MIT-0 License. See the LICENSE file.