Feature status: Limited Availability (LA)
Overview
To use Amazon Core Managed Instance (CMI) with Horizon Cloud, you must prepare a Windows image by importing a supported Windows ISO into AWS, creating a base AMI using EC2 Image Builder, and then customizing the AMI with the Horizon Agent installer (HAI) using EC2 Image Builder components, image recipes, and pipelines.
This topic describes the common preparation steps and the CMI-specific image customization workflow.
Note: This method is separate from the Amazon WorkSpaces Core methods (Method 1: AWS EC2 Custom Instance Import, Method 2, and Method 3). Do not combine the steps described here with those methods, as the workflows differ.
Common Preparation Steps
Before you can create a Windows image for CMI, complete the following preparation tasks in order. These steps ensure that your environment, permissions, and source image are ready for use with AWS EC2 Image Builder.
For the detailed procedure for each step, see Common Preparation Steps for Creating Windows Images for Horizon on AWS.
-
Obtain a supported Windows ISO for Horizon on AWS - Download a supported Windows ISO (e.g., Windows 11 Enterprise 25H2 or 24H2) from the official Microsoft website.
-
Upload the Windows ISO to an Amazon S3 bucket - Upload the ISO file to an Amazon S3 bucket accessible to AWS Image Builder. The ISO file extension must be in uppercase (for example,
Windows11.ISO). -
Create an IAM role for EC2 Image Builder - Create an IAM role with the following permission policies:
AmazonSSMManagedInstanceCoreEC2InstanceProfileForImageBuilderEC2InstanceProfileForImageBuilderECRContainerBuilds
-
Create an EC2 Image Builder Infrastructure Configuration - Define the compute, networking, and notification settings used during image build and test operations, including instance type, VPC, subnet, security group, and SNS topic.
Import the Windows ISO and Create a Base AMI
After completing the common preparation steps, import the Windows ISO into AWS using EC2 Image Builder to create a base Amazon Machine Image (AMI). The resulting AMI is later used as the parent image for the image recipe.
Procedure
- From the AWS Management Console, go to EC2 Image Builder.
- In the navigation pane, choose Images.
- Choose Import image.
- In the General section, provide the following information:
- Name - Enter a unique name for the image.
- Version - Specify a version number using the format
major.minor.patch.
- For Import type, select ISO import.
- In the ISO import configuration section, provide the following details:
- S3 URI - Specify the Amazon S3 location where the Windows ISO file is stored.
- IAM role - Select the IAM role you created in the common preparation steps.
- For ISO infrastructure configuration, select the infrastructure configuration you created in the common preparation steps.
- Choose Import image to start the ISO import process.
- Monitor the import status in EC2 Image Builder until the image creation completes successfully.
Validate the Base AMI
After the ISO import is complete, validate that the base AMI is available before proceeding:
- In EC2 Image Builder, navigate to Images.
- Locate the image created from the ISO import.
- Verify that the Last success status shows as Available.
Customize the Windows AMI with the Horizon Agent Installer
After the base AMI is created and validated, customize it with the Horizon Agent installer using EC2 Image Builder components, an image recipe, and an image pipeline. This approach automates the customization without requiring a manual RDP session.
Step 1: Create Custom EC2 Image Builder Components
Create custom components in EC2 Image Builder to automate the installation of the Horizon Agent and the configuration of OOBE settings. Each component is defined as a YAML document.
To create a custom component:
- In EC2 Image Builder, navigate to Components and click Create component.
- For the image operating system, select Windows. The OS version is determined by the ISO and does not need to be specified.
- Leave the KMS server as the default value.
- Define the component content using the YAML document format.
- Click Create component.
Create the following four components. The order in which these components are added to the image recipe (in the next step) is critical.
Component 1: Pre-Install RunOnce Backup
Backs up all HKLM RunOnce keys (64-bit and Wow6432Node) to C:\Windows\Temp, then removes all RunOnce values so the Horizon Agent installer does not detect a pending reboot (exit 0x643). Run this component immediately before the Horizon Agent install component.
# DISCLAIMER:
# This script/YAML file is provided as a sample for reference purposes only.
# It is not intended for production use without proper review, testing, and validation.
# Users are responsible for evaluating and modifying the content to meet their
# security, compliance, and operational requirements.
# No warranties or guarantees are provided.
name: HorizonAgentPreInstallRunOnceBackup
description: Backs up all HKLM RunOnce keys/values (64-bit and Wow6432Node) to C:\Windows\Temp, then removes all RunOnce values so the Horizon Agent installer does not detect a pending reboot (exit 0x643). Run immediately before the Horizon Agent install component.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ShowRunOnceValues
action: ExecutePowerShell
onFailure: Continue
inputs:
commands:
- |
foreach ($p in 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce',
'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\RunOnce') {
Write-Host "== $p =="
Get-ItemProperty -Path $p -ErrorAction SilentlyContinue | Format-List
}
- name: BackupAllRunOnceKeys
action: ExecutePowerShell
onFailure: Abort
inputs:
commands:
- |
$targets = @(
@{ Reg = 'HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce'; Ps = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce'; File = 'C:\Windows\Temp\RunOnce_HKLM_backup' },
@{ Reg = 'HKLM\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\RunOnce'; Ps = 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\RunOnce'; File = 'C:\Windows\Temp\RunOnce_HKLM_Wow6432Node_backup' }
)
foreach ($t in $targets) {
if (-not (Test-Path $t.Ps)) {
Write-Host "Key not present, skipping: $($t.Reg)"
continue
}
$regFile = "$($t.File).reg"
& reg.exe export $t.Reg $regFile /y
if ($LASTEXITCODE -ne 0) { Write-Error "reg export failed ($LASTEXITCODE) for $($t.Reg)"; exit 1 }
if (-not (Test-Path $regFile)) { Write-Error "Backup file not found: $regFile"; exit 1 }
Write-Host "Backup written to $regFile"
$jsonFile = "$($t.File).json"
$items = @(Get-Item -Path $t.Ps) + @(Get-ChildItem -Path $t.Ps -Recurse -ErrorAction SilentlyContinue)
$rows = foreach ($k in $items) {
foreach ($n in $k.GetValueNames()) {
[pscustomobject]@{
Key = $k.Name
Name = $n
Type = $k.GetValueKind($n).ToString()
Value = $k.GetValue($n, $null, 'DoNotExpandEnvironmentNames')
}
}
}
@($rows) | ConvertTo-Json -Depth 4 | Set-Content -Path $jsonFile -Encoding UTF8
Write-Host "Value inventory written to $jsonFile ($(@($rows).Count) values)"
}
- name: RemoveAllRunOnceValues
action: ExecutePowerShell
onFailure: Abort
inputs:
commands:
- |
# SAFETY: $true = log only (dry run). Set to $false to actually delete.
$DryRun = $false
$roots = @(
'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce',
'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\RunOnce'
)
foreach ($root in $roots) {
if (-not (Test-Path $root)) { Write-Host "Key not present, skipping: $root"; continue }
# Root key plus any subkeys (e.g. RunOnce\Setup). Subkeys themselves are kept; only values are removed.
$keys = @(Get-Item -Path $root) + @(Get-ChildItem -Path $root -Recurse -ErrorAction SilentlyContinue)
foreach ($k in $keys) {
foreach ($n in $k.GetValueNames()) {
if ([string]::IsNullOrEmpty($n)) { continue } # skip (Default)
if ($DryRun) {
Write-Host "[DRY RUN] Would remove '$n' from $($k.Name)"
} else {
Remove-ItemProperty -LiteralPath $k.PSPath -Name $n -ErrorAction Stop
Write-Host "Removed '$n' from $($k.Name)"
}
}
}
}
exit 0
Component 2: Install Omnissa Horizon Agents
Downloads and silently installs the Omnissa Horizon Agents Installer. The installer is resilient -- if it encounters a 1603 error, it reboots and retries (up to 2 times).
# DISCLAIMER:
# This script/YAML file is provided as a sample for reference purposes only.
# It is not intended for production use without proper review, testing, and validation.
# Users are responsible for evaluating and modifying the content to meet their
# security, compliance, and operational requirements.
# No warranties or guarantees are provided.
name: InstallOmnissaHorizonAgents
description: Downloads and silently installs Omnissa Horizon Agents Installer 26.3.0 (resilient, reboot-and-retry on 1603)
schemaVersion: 1.0
phases:
- name: build
steps:
- name: CheckPendingReboot
action: ExecutePowerShell
onFailure: Continue
inputs:
commands:
- |
$pending = @()
if (Test-Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing\RebootPending') { $pending += 'CBS' }
if (Test-Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\RebootRequired') { $pending += 'WindowsUpdate' }
$pfro = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager' -Name PendingFileRenameOperations -ErrorAction SilentlyContinue).PendingFileRenameOperations
if ($pfro) { $pending += 'PendingFileRename' }
if ($pending.Count -gt 0) {
Write-Warning "Pending reboot detected ($($pending -join ', ')). Skipping reboot and continuing installation."
} else {
Write-Host "No pending reboot detected."
}
exit 0
- name: DownloadHorizonAgents
action: WebDownload
maxAttempts: 3
timeoutSeconds: 1800
onFailure: Abort
inputs:
- source: https://softwareupdate.omnissa.com/horizoncloud-v2-agents/packages/HAI-Agent/26.3.0/40775428445/Omnissa-Horizon-Agents-Installer-26.3.0-40775428445-x64.exe
destination: C:\Windows\Temp\Omnissa-Horizon-Agents-Installer.exe
overwrite: true
- name: InstallHorizonAgents
action: ExecutePowerShell
maxAttempts: 2
timeoutSeconds: 3600
onFailure: Abort
inputs:
commands:
- |
$ErrorActionPreference = 'Stop'
$installer = 'C:\Windows\Temp\Omnissa-Horizon-Agents-Installer.exe'
$sourceUrl = 'https://softwareupdate.omnissa.com/horizoncloud-v2-agents/packages/HAI-Agent/26.3.0/40775428445/Omnissa-Horizon-Agents-Installer-26.3.0-40775428445-x64.exe'
$log = 'C:\Windows\Temp\HorizonAgents_install_wrapper.log'
$retryFile = 'C:\Windows\Temp\HorizonAgents_1603_retry.txt' # survives reboot
$maxRebootRetries = 2
function Log($m) { "$(Get-Date -Format s) $m" | Out-File $log -Append; Write-Host $m }
$retryCount = 0
if (Test-Path $retryFile) { $retryCount = [int](Get-Content $retryFile -Raw) }
if ($retryCount -gt 0) { Log "Resuming after reboot (1603 retry #$retryCount)." }
# Idempotency check - skipped during 1603 retries (failed installs can leave partial uninstall entries)
if ($retryCount -eq 0) {
$keys = @(
'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*',
'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'
)
$existing = Get-ItemProperty $keys -ErrorAction SilentlyContinue |
Where-Object { $_.DisplayName -like '*Omnissa Horizon*' }
if ($existing) { Log "Already installed: $($existing.DisplayName -join ', '). Skipping."; exit 0 }
}
# Re-download if installer is missing after reboot
if (-not (Test-Path $installer)) {
Log "Installer missing. Re-downloading..."
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri $sourceUrl -OutFile $installer -UseBasicParsing
if (-not (Test-Path $installer)) { Log "ERROR: Re-download failed."; exit 1 }
}
Log "Starting install..."
$p = Start-Process -FilePath $installer -ArgumentList '/silent','/norestart' -Wait -PassThru
$code = $p.ExitCode
Log "Installer exit code: $code"
switch ($code) {
0 { Remove-Item $retryFile -Force -ErrorAction SilentlyContinue; Log "Install succeeded."; exit 0 }
3010 { Remove-Item $retryFile -Force -ErrorAction SilentlyContinue; Log "Install succeeded; reboot handled by next step."; exit 0 }
1641 { Remove-Item $retryFile -Force -ErrorAction SilentlyContinue; Log "Install succeeded; installer initiated reboot."; exit 0 }
1603 {
if ($retryCount -lt $maxRebootRetries) {
$retryCount++
Set-Content -Path $retryFile -Value $retryCount
Log "1603 received. Rebooting and retrying ($retryCount of $maxRebootRetries)..."
exit 3010 # AWSTOE: reboot the instance, then re-run this step
}
Log "ERROR: 1603 persisted after $maxRebootRetries reboot/retry cycles."
Remove-Item $retryFile -Force -ErrorAction SilentlyContinue
exit 1603
}
default { Log "ERROR: Install failed with exit code $code"; exit $code }
}
- name: RebootAfterInstall
action: Reboot
onFailure: Continue
inputs:
delaySeconds: 30
- name: CleanupInstaller
action: ExecutePowerShell
onFailure: Continue
inputs:
commands:
- |
Remove-Item 'C:\Windows\Temp\Omnissa-Horizon-Agents-Installer.exe' -Force -ErrorAction SilentlyContinue
Remove-Item 'C:\Windows\Temp\HorizonAgents_1603_retry.txt' -Force -ErrorAction SilentlyContinue
exit 0
- name: validate
steps:
- name: VerifyInstallation
action: ExecutePowerShell
onFailure: Continue
inputs:
commands:
- |
$keys = @(
'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*',
'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'
)
$found = Get-ItemProperty $keys -ErrorAction SilentlyContinue |
Where-Object { $_.DisplayName -like '*Omnissa Horizon*' }
if ($found) {
$found | ForEach-Object { Write-Host "Installed: $($_.DisplayName) $($_.DisplayVersion)" }
} else {
Write-Warning "Omnissa Horizon Agents not found"
}
exit 0
Component 3: Post-Install RunOnce Restore
Restores all HKLM RunOnce keys from the C:\Windows\Temp backups created by the pre-install backup component, verifies them against the value inventory, then reboots.
# DISCLAIMER:
# This script/YAML file is provided as a sample for reference purposes only.
# It is not intended for production use without proper review, testing, and validation.
# Users are responsible for evaluating and modifying the content to meet their
# security, compliance, and operational requirements.
# No warranties or guarantees are provided.
name: HorizonAgentPostInstallRunOnceRestore
description: Restores all HKLM RunOnce keys/values (64-bit and Wow6432Node) from the C:\Windows\Temp backups created by HorizonAgentPreInstallRunOnceBackup after the Horizon Agent install, verifies them against the value inventory, then reboots.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ImportRunOnceBackups
action: ExecutePowerShell
onFailure: Abort
inputs:
commands:
- |
$backups = @(
'C:\Windows\Temp\RunOnce_HKLM_backup.reg',
'C:\Windows\Temp\RunOnce_HKLM_Wow6432Node_backup.reg'
)
$imported = 0
foreach ($b in $backups) {
if (-not (Test-Path $b)) {
# Backup step skips keys that did not exist, so a missing file is not an error
Write-Host "Backup not found, skipping: $b"
continue
}
& reg.exe import $b
if ($LASTEXITCODE -ne 0) { Write-Error "reg import failed ($LASTEXITCODE) for $b"; exit 1 }
Write-Host "Imported $b"
$imported++
}
if ($imported -eq 0) { Write-Error "No RunOnce backup files found in C:\Windows\Temp"; exit 1 }
- name: VerifyRestoredRunOnceValues
action: ExecutePowerShell
onFailure: Continue
inputs:
commands:
- |
$inventories = @(
@{ Json = 'C:\Windows\Temp\RunOnce_HKLM_backup.json' },
@{ Json = 'C:\Windows\Temp\RunOnce_HKLM_Wow6432Node_backup.json' }
)
$missing = 0; $checked = 0
foreach ($i in $inventories) {
if (-not (Test-Path $i.Json)) { Write-Host "Inventory not found, skipping: $($i.Json)"; continue }
$rows = @(Get-Content -Raw -Path $i.Json | ConvertFrom-Json)
foreach ($r in $rows) {
if ($null -eq $r -or [string]::IsNullOrEmpty($r.Name)) { continue }
$checked++
$psKey = 'Registry::' + $r.Key
$cur = Get-ItemProperty -LiteralPath $psKey -Name $r.Name -ErrorAction SilentlyContinue
if ($cur) { Write-Host "Restored: $($r.Key)\$($r.Name)" }
else { Write-Warning "NOT restored: $($r.Key)\$($r.Name)"; $missing++ }
}
}
Write-Host "Checked $checked values; $missing missing"
- name: RebootAfterRestore
action: Reboot
onFailure: Abort
inputs:
delaySeconds: 60
- name: CleanupBackups
action: ExecutePowerShell
onFailure: Continue
inputs:
commands:
- |
Remove-Item -Path 'C:\Windows\Temp\RunOnce_HKLM_backup.reg',
'C:\Windows\Temp\RunOnce_HKLM_backup.json',
'C:\Windows\Temp\RunOnce_HKLM_Wow6432Node_backup.reg',
'C:\Windows\Temp\RunOnce_HKLM_Wow6432Node_backup.json' -Force -ErrorAction SilentlyContinue
Write-Host "Backup files removed"
Component 4: Configure OOBE Unattend
Adds OOBE, UserAccounts, AutoLogon, and locale/keyboard settings to the EC2Launch v2 Sysprep unattend file to avoid manual OS input during setup.
# DISCLAIMER:
# This script/YAML file is provided as a sample for reference purposes only.
# It is not intended for production use without proper review, testing, and validation.
# Users are responsible for evaluating and modifying the content to meet their
# security, compliance, and operational requirements.
# No warranties or guarantees are provided.
name: ConfigureOOBEUnattend
description: Adds OOBE, UserAccounts, AutoLogon and locale/keyboard settings to the EC2Launch v2 Sysprep unattend file
schemaVersion: 1.0
phases:
- name: build
steps:
- name: UpdateEC2LaunchUnattend
action: ExecutePowerShell
onFailure: Abort
inputs:
commands:
- |
$path = 'C:\ProgramData\Amazon\EC2Launch\sysprep\unattend.xml'
if (-not (Test-Path $path)) { Write-Host "ERROR: $path not found"; exit 1 }
Copy-Item $path "$path.bak" -Force
[xml]$xml = Get-Content $path
$uri = 'urn:schemas-microsoft-com:unattend'
$ns = New-Object System.Xml.XmlNamespaceManager($xml.NameTable)
$ns.AddNamespace('u', $uri)
$shell = $xml.SelectSingleNode("//u:settings[@pass='oobeSystem']/u:component[@name='Microsoft-Windows-Shell-Setup']", $ns)
if (-not $shell) { Write-Host "ERROR: oobeSystem Shell-Setup component not found"; exit 1 }
# Create/set a nested element path under a parent, e.g. Set-Node $shell @('OOBE','HideEULAPage') 'true'
function Set-Node($parent, [string[]]$names, [string]$value) {
$cur = $parent
foreach ($name in $names) {
$child = $cur.SelectSingleNode("u:$name", $ns)
if (-not $child) { $child = $xml.CreateElement($name, $uri); [void]$cur.AppendChild($child) }
$cur = $child
}
$cur.InnerText = $value
}
# Random throwaway password generated at build time (never logged, never stored in source).
# EC2Launch resets the Administrator password at instance launch.
$bytes = New-Object byte[] 18
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$pw = [Convert]::ToBase64String($bytes) + 'aA1!'
# UserAccounts
Set-Node $shell @('UserAccounts','AdministratorPassword','Value') $pw
Set-Node $shell @('UserAccounts','AdministratorPassword','PlainText') 'true'
# AutoLogon
Set-Node $shell @('AutoLogon','Username') 'Administrator'
Set-Node $shell @('AutoLogon','Enabled') 'true'
Set-Node $shell @('AutoLogon','LogonCount') '1'
Set-Node $shell @('AutoLogon','Password','Value') $pw
Set-Node $shell @('AutoLogon','Password','PlainText') 'true'
# OOBE
$oobe = [ordered]@{
HideEULAPage = 'true'
ProtectYourPC = '3'
HideWirelessSetupInOOBE = 'true'
HideOnlineAccountScreens = 'true'
NetworkLocation = 'Work'
}
foreach ($k in $oobe.Keys) { Set-Node $shell @('OOBE', $k) $oobe[$k] }
# Locale / keyboard (pre-answers the Country, Keyboard layout and Second keyboard OOBE pages)
$settingsNode = $shell.ParentNode
$intl = $settingsNode.SelectSingleNode("u:component[@name='Microsoft-Windows-International-Core']", $ns)
if (-not $intl) {
$intl = $xml.CreateElement('component', $uri)
$attrs = [ordered]@{ name='Microsoft-Windows-International-Core'; processorArchitecture='amd64'; publicKeyToken='31bf3856ad364e35'; language='neutral'; versionScope='nonSxS' }
foreach ($a in $attrs.Keys) { $intl.SetAttribute($a, $attrs[$a]) }
[void]$settingsNode.AppendChild($intl)
}
$locale = [ordered]@{
InputLocale = '0409:00000409' # single US keyboard; no secondary layout page
SystemLocale = 'en-US'
UILanguage = 'en-US'
UserLocale = 'en-US' # sets country/region format
}
foreach ($k in $locale.Keys) { Set-Node $intl @($k) $locale[$k] }
$xml.Save($path)
Write-Host "Updated $path"
- name: validate
steps:
- name: VerifyUnattendSettings
action: ExecutePowerShell
onFailure: Abort
inputs:
commands:
- |
$path = 'C:\ProgramData\Amazon\EC2Launch\sysprep\unattend.xml'
[xml]$xml = Get-Content $path
$ns = New-Object System.Xml.XmlNamespaceManager($xml.NameTable)
$ns.AddNamespace('u', 'urn:schemas-microsoft-com:unattend')
$base = "//u:settings[@pass='oobeSystem']/u:component[@name='Microsoft-Windows-Shell-Setup']"
$ic = "//u:settings[@pass='oobeSystem']/u:component[@name='Microsoft-Windows-International-Core']"
$checks = [ordered]@{
"$base/u:OOBE/u:HideEULAPage" = 'true'
"$base/u:OOBE/u:ProtectYourPC" = '3'
"$base/u:OOBE/u:HideWirelessSetupInOOBE" = 'true'
"$base/u:OOBE/u:HideOnlineAccountScreens" = 'true'
"$base/u:OOBE/u:NetworkLocation" = 'Work'
"$base/u:AutoLogon/u:Username" = 'Administrator'
"$base/u:AutoLogon/u:Enabled" = 'true'
"$base/u:AutoLogon/u:LogonCount" = '1'
"$ic/u:InputLocale" = '0409:00000409'
"$ic/u:SystemLocale" = 'en-US'
"$ic/u:UILanguage" = 'en-US'
"$ic/u:UserLocale" = 'en-US'
}
$failed = $false
foreach ($xp in $checks.Keys) {
$n = $xml.SelectSingleNode($xp, $ns)
if (-not $n -or $n.InnerText -ne $checks[$xp]) { Write-Host "ERROR: missing/incorrect $xp"; $failed = $true }
}
# Presence-only checks for password nodes (values are never printed)
foreach ($xp in @("$base/u:UserAccounts/u:AdministratorPassword/u:Value", "$base/u:AutoLogon/u:Password/u:Value")) {
$n = $xml.SelectSingleNode($xp, $ns)
if (-not $n -or [string]::IsNullOrEmpty($n.InnerText)) { Write-Host "ERROR: missing $xp"; $failed = $true }
}
if ($failed) { exit 1 }
Write-Host "OOBE, UserAccounts, AutoLogon and locale settings present in $path"
Step 2: Create the Image Recipe
After creating the components, create an image recipe that combines the base AMI (created from the ISO import) with the custom components in a specific order.
To create the image recipe:
- In EC2 Image Builder, navigate to Image recipes and click Create recipe.
- Select the image created from the ISO import as the base/parent image.
- Select the infrastructure configuration.
- Add the build components in the following exact order:
| Order | Component | Purpose |
|---|---|---|
| 1 | HorizonAgentPreInstallRunOnceBackup | Backs up RunOnce keys so the HAI installer does not detect a pending reboot |
| 2 | InstallOmnissaHorizonAgents | Installs the Omnissa Horizon Agent |
| 3 | HorizonAgentPostInstallRunOnceRestore | Restores the backed-up RunOnce keys |
| 4 | ConfigureOOBEUnattend | Configures OOBE, autologon, and locale settings |
- Select the distribution settings.
- Click Create recipe.
Important: The component order is critical. The Pre-Install RunOnce Backup must run before the HAI installer so that the installer does not detect a pending reboot (exit 0x643). The Post-Install RunOnce Restore must run after the HAI installer to restore the backed-up keys.
Step 3: Create the Image Pipeline
After creating the image recipe, create an image pipeline that combines the component, recipe, and infrastructure configuration to produce the finalized AMI.
To create the image pipeline:
- In EC2 Image Builder, navigate to Pipelines and click Create pipeline.
- In the General section, enter a name for the pipeline.
- Choose the execution type:
- Manual - Run the pipeline on demand.
- Scheduled - Run the pipeline on a schedule.
- Select the image recipe and its version.
- Verify that the components are listed in the correct order (PreInstall RunOnce → HAI → PostInstall RunOnce → OOBE).
- Leave the workflow as default.
- Select the infrastructure configuration created in the common preparation steps.
- Configure the distribution settings (use existing or create new).
- Click Create pipeline.
Pipeline workflow stages:
- Build - Launches a build instance, waits for SSM agent readiness, runs the build components, creates an AMI from the customized instance, and terminates the build instance.
- Test - Launches a fresh instance from the new AMI, runs test components, and collects results. If any test fails, the image is marked as failed.
- Distribution (optional) - Copies the AMI to target Regions and applies sharing settings.
To run the pipeline:
- Select the pipeline, then choose Actions > Run pipeline.
- The workflow engine orchestrates: Build → Test → Distribution.
- To view the output image, select the pipeline > Output images > choose the version. Under Output resources, the AMI ID is shown.
For additional guidance on building an EC2 Image Builder pipeline, refer to the AWS Builder Center article: Build an EC2 Image Builder Pipeline for the Amazon WorkSpaces -- A Step-by-Step Guide.
Step 4: Verify the Image and Register in Horizon Cloud IMS
After the pipeline completes, verify the image and register it in Horizon Cloud for CMI-based image creation.
- In EC2 Image Builder, navigate to the pipeline and check that the image status shows as Available.
- (Optional) Launch a test instance from the created AMI to verify the configuration:
- Select the AMI, click Launch instance from AMI.
- Provide the key pair details.
- Log in to the instance and verify that the Horizon Agent and all configurations are correct.
- Once verified, register the AMI in the Horizon Cloud Image Management Service (IMS) for CMI-based image creation. For details, see the Horizon Cloud console image import workflow.
Note: CMI image registration in Horizon Cloud is documented separately. See Register an AWS CMI Image Using an AMI for the registration procedure.
Related References
- Common Preparation Steps for Creating Windows Images for Horizon on AWS
- Method 1: AWS EC2 Custom Instance Import
- Prepare to Add an Image with Amazon WorkSpaces Core
- Build an EC2 Image Builder Pipeline for the Amazon WorkSpaces -- A Step-by-Step Guide (AWS Builder Center)
- Creating a custom component with Image Builder (AWS documentation)
- Create a new version of an image recipe (AWS documentation)
- Create an image pipeline (AWS documentation)
Was this page helpful?