AWS Builder Center

Builder Center

Build an EC2 Image Builder Pipeline for the Amazon WorkSpaces - A Step-by-Step Guide

This is the hands-on companion to Automate Custom Image Builds with EC2 Image Builder for Amazon WorkSpaces blog article. This article is co-authored by Shantanu Padhye, Sr. Solutions Architect, Agentic WorkSpaces, AWS

Mayank Jain

Introduction 

In this  blog , we made the case for why automating golden image creation matters. We talked about the pain of monthly manual builds, the risk of configuration drift, and how EC2 Image Builder pipelines solve those problems at the platform level. If you haven’t read blog yet, we’d recommend starting there for the full context.
Now it’s time to roll up our sleeves and build something. In this walkthrough, we’ll create an EC2 Image Builder pipeline from scratch — one that installs three common Windows applications, Notepad++, Google Chrome, and Visual Studio Code, validates that each one is working, and produces a ready-to-use Amazon Machine Image (AMI). That AMI can then be imported into WorkSpaces Personal (BYOL), WorkSpaces Core Bundles (BYOL), WorkSpaces Applications, and WorkSpaces Core Managed Instances.
We chose these three applications deliberately. Notepad++ gives us a lightweight EXE-based installer with silent flags. Chrome brings in an MSI-based installation (which needs msiexec handling). And VS Code rounds things out with an Inno Setup-based system installer that deploys to Program Files for all users — an important distinction since golden images serve multiple user sessions. Between the three, you’ll see enough variety in the component YAML to handle any software your users need.
Let’s get started.

What you’ll need before starting

Before diving in, make sure you meet the following prerequisites:
  • An AWS account with full access to EC2, EC2 Image Builder, WorkSpaces Personal, WorkSpaces Applications and Amazon S3 bucket.
  • An  IAM Instance Profile  role with the AmazonSSMManagedInstanceCore, EC2InstanceProfileForImageBuilder, and AmazonS3ReadOnlyAccess managed policies attached.
  • An IAM execution role with the EC2ImageBuilderExecutionPolicy managed policy attached. This is the role Image Builder assumes to run workflow actions (separate from the instance profile).
  • A base Windows AMI — Windows 11, Windows Server 2022, or Windows Server 2025. Any of these will work since the installers we’re using are the same across client and server editions.
  • For WorkSpaces Applications, EC2 image import requires additional  AMI properties .
  • (Optional) An S3 bucket with the application installer files pre-staged, if you prefer the S3 download approach over pulling directly from vendor URLs.
  • Basic familiarity with the AWS Management Console. We’ll walk through each click, but knowing your way around helps.
  • A VPC with private subnets and connectivity to internet for service endpoints and Windows Update services.

What we’re building

Here’s the plan briefly:
  1. Create a custom build component — the YAML that downloads and installs the applications and Windows updates.
  1. Create a custom test component — the YAML that validates that each application is installed and runs correctly.
  1. Create an image recipe combining a Windows base image with our custom components.
  1. Create a custom image workflow – the YAML that defines the sequence of steps that EC2 Image Builder runs during one stage (build, test, and distribution stage) of the image creation process.
  1. Configure infrastructure and distribution settings.
  1. Assemble the pipeline and run it.
  1. Import the resulting AMI into the WorkSpaces service of your choice.
We’ll show two approaches for sourcing installers: download from the vendor URL during the build (always get the latest) or pull from an S3 bucket you control (better for air-gapped environments or pinned versions). Both are shown side by side in the component YAML.

Step 1: Create the custom build component

Components are the building blocks of your image customization. Each component is a YAML document that defines a series of steps that Image Builder runs on the EC2 instance to customize or test your image. We create build components to install and configure what goes into our image, and test components to validate that everything works after the build is complete.
The build component defines every customization step: creating folders, downloading installers, running them silently, rebooting, and cleaning up.

Creating the build component in the console

  1. Open the  EC2 Image Builder console .
  1. In the left navigation, under Saved resources, choose Components.
  1. Choose Create component.
  1. For Component Name specify a name of your choice. For example, Install-Custom-Apps-NotepadPP-Chrome-VSCode.
  1. For Component version specify 1.0.0.
  1. For Description, provide a description. For example, Installs Notepad++, Google Chrome, and VS Code (System) for custom WorkSpaces images.
  1. For Image Operating System (OS), select Windows.
  1. Under Definition document, select Define document content and paste the below YAML.
  1. Choose Create component.

The build component YAML

Here’s the full component document. For each application, the active approach uses WebDownload (vendor URL). The S3Download alternative is commented out. Replace s3://your-bucket-name/installers/ with your actual bucket path and the installer file name if using S3. You can use the S3 approach if the subnet where the build instance (created later in this article) doesn't have internet access. The IAM execution role used by EC2 Image Builder should also have read permission to the S3 bucket that stores the installer files.
YAML
name: Install-Custom-Apps-Build
description: Installs Notepad++, Google Chrome, and VS Code (System Installer).
schemaVersion: 1.0
phases:
  - name: build
    steps:
      # Create a temporary staging folder
      - name: CreateStagingDirectory
        action: CreateFolder
        inputs:
          - path: C:\ImageBuilderStaging

      # =========================================================
      # NOTEPAD++ (NSIS EXE installer, silent flag: /S)
      # =========================================================

      # Option A - Download from vendor
      - name: DownloadNotepadPP
        action: WebDownload
        maxAttempts: 3
        inputs:
          - source: https://github.com/notepad-plus-plus/notepad-plus-plus/releases/download/v8.7.1/npp.8.7.1.Installer.x64.exe
            destination: C:\ImageBuilderStaging\npp_installer.exe
            overwrite: true

      # Option B - Download from S3 (uncomment to use)
      # - name: DownloadNotepadPPFromS3
      #   action: S3Download
      #   inputs:
      #     - source: s3://your-bucket-name/installers/npp_installer.exe
      #       destination: C:\ImageBuilderStaging\npp_installer.exe
      #       overwrite: true

      - name: InstallNotepadPP
        action: ExecuteBinary
        onFailure: Abort
        inputs:
          path: C:\ImageBuilderStaging\npp_installer.exe
          arguments:
            - /S

      # =========================================================
      # GOOGLE CHROME (MSI installer via msiexec)
      # =========================================================

      # Option A - Download from vendor
      - name: DownloadChrome
        action: WebDownload
        maxAttempts: 3
        inputs:
          - source: https://dl.google.com/dl/chrome/install/googlechromestandaloneenterprise64.msi
            destination: C:\ImageBuilderStaging\chrome_installer.msi
            overwrite: true

      # Option B - Download from S3 (uncomment to use)
      # - name: DownloadChromeFromS3
      #   action: S3Download
      #   inputs:
      #     - source: s3://your-bucket-name/installers/chrome_installer.msi
      #       destination: C:\ImageBuilderStaging\chrome_installer.msi
      #       overwrite: true

      - name: InstallChrome
        action: ExecutePowerShell
        onFailure: Abort
        inputs:
          commands:
            - |
              $msiArgs = "/i C:\ImageBuilderStaging\chrome_installer.msi /qn /norestart"
              $proc = Start-Process msiexec.exe -ArgumentList $msiArgs -Wait -PassThru
              if ($proc.ExitCode -ne 0 -and $proc.ExitCode -ne 3010) {
                Write-Error "Chrome install failed with exit code $($proc.ExitCode)"
                exit 1
              }
              Write-Host "Google Chrome installed successfully."

      # =========================================================
      # VISUAL STUDIO CODE - SYSTEM INSTALLER (Inno Setup)
      # Important: We use the System Installer, NOT the User Installer.
      # The System Installer deploys to C:\Program Files and is available
      # to all users - critical for golden/shared images.
      # =========================================================

      # Option A - Download from vendor
      - name: DownloadVSCode
        action: WebDownload
        maxAttempts: 3
        inputs:
          - source: https://code.visualstudio.com/sha/download?build=stable&os=win32-x64
            destination: C:\ImageBuilderStaging\VSCodeSetup-x64.exe
            overwrite: true

      # Option B - Download from S3 (uncomment to use)
      # - name: DownloadVSCodeFromS3
      #   action: S3Download
      #   inputs:
      #     - source: s3://your-bucket-name/installers/VSCodeSetup-x64.exe
      #       destination: C:\ImageBuilderStaging\VSCodeSetup-x64.exe
      #       overwrite: true

      - name: InstallVSCode
        action: ExecuteBinary
        onFailure: Abort
        inputs:
          path: C:\ImageBuilderStaging\VSCodeSetup-x64.exe
          arguments:
            - /VERYSILENT
            - /NORESTART
            - /SUPPRESSMSGBOXES
            - /MERGETASKS=!runcode,addcontextmenufiles,addcontextmenufolders,addtopath

      # Reboot to let all installs settle
      - name: RebootAfterInstall
        action: Reboot

      # Clean up staging directory
      - name: CleanupStaging
        action: DeleteFolder
        inputs:
          - path: C:\ImageBuilderStaging
            force: true

Step 2: Create the custom test component

A build component gets software onto the image. A test component makes sure it actually works. If you skip testing, you might ship a golden image where an app silently failed to register. You’ll only find out when users start complaining.
Our test does a smoke test for each application, check the executable exists at the expected system path, launch it, confirm the process is running, and shut it down.

Creating the test component in console

  1. Open the  EC2 Image Builder console .
  1. In the left navigation, under Saved resources, choose Components.
  1. Choose Create component.
  1. For Component Name specify a name of your choice. For example: Test-Custom-Apps-NotepadPP-Chrome-VSCode.
  1. For Component version specify 1.0.0.
  1. For Description, provide a description. For example: Validates Notepad++, Chrome, and VS Code are installed and can launch.
  1. For Image Operating System (OS), select Windows.
  1. Under Definition document, select Define document content and paste the YAML below.
  1. Choose Create component.

The test component YAML

Note: Image Builder classifies this as a test component automatically because it contains only a "test" phase.
YAML
name: Test-Custom-Apps
description: Smoke tests for Notepad++, Google Chrome, and VS Code.
schemaVersion: 1.0
phases:
  - name: test
    steps:
      # --- Test 1: Notepad++ ---

      - name: TestNotepadPP
        action: ExecutePowerShell
        onFailure: Abort
        inputs:
          commands:
            - |
              $exePath = "C:\Program Files\Notepad++\notepad++.exe"
              if (-Not (Test-Path $exePath)) {
                Write-Error "FAIL: Notepad++ not found at $exePath"
                exit 1
              }
              Write-Host "PASS: Notepad++ executable exists."
              $proc = Start-Process -FilePath $exePath -PassThru
              Start-Sleep -Seconds 5
              $running = Get-Process -Name "notepad++" -ErrorAction SilentlyContinue
              if ($null -eq $running) {
                Write-Error "FAIL: Notepad++ process not found."
                exit 1
              }
              Write-Host "PASS: Notepad++ is running (PID: $($proc.Id))"
              Stop-Process -Name "notepad++" -Force
              Write-Host "Notepad++ smoke test passed."

      # --- Test 2: Google Chrome ---

      - name: TestChrome
        action: ExecutePowerShell
        onFailure: Abort
        inputs:
          commands:
            - |
              $exePath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
              if (-Not (Test-Path $exePath)) {
                Write-Error "FAIL: Chrome not found at $exePath"
                exit 1
              }
              Write-Host "PASS: Chrome executable exists."
              $proc = Start-Process -FilePath $exePath `
                -ArgumentList "--headless","--disable-gpu","--no-sandbox" -PassThru
              Start-Sleep -Seconds 5
              $running = Get-Process -Name "chrome" -ErrorAction SilentlyContinue
              if ($null -eq $running) {
                Write-Error "FAIL: Chrome process not found."
                exit 1
              }
              Write-Host "PASS: Chrome is running (PID: $($proc.Id))"
              Stop-Process -Name "chrome" -Force -ErrorAction SilentlyContinue
              Write-Host "Chrome smoke test passed."

      # --- Test 3: Visual Studio Code ---

      - name: TestVSCode
        action: ExecutePowerShell
        onFailure: Abort
        inputs:
          commands:
            - |
              $exePath = "C:\Program Files\Microsoft VS Code\Code.exe"
              if (-Not (Test-Path $exePath)) {
                Write-Error "FAIL: VS Code not found at $exePath"
                exit 1
              }
              Write-Host "PASS: VS Code executable exists at $exePath"

              # Launch VS Code and verify process
              
              $proc = Start-Process -FilePath $exePath -PassThru
              Start-Sleep -Seconds 8
              $running = Get-Process -Name "Code" -ErrorAction SilentlyContinue
              if ($null -eq $running) {
                Write-Error "FAIL: VS Code process not found."
                exit 1
              }
              Write-Host "PASS: VS Code is running (PID: $($proc.Id))"

              # Also verify it installed to system context (not user profile)
              
              $inProgramFiles = $exePath.StartsWith("C:\Program Files")
              if (-Not $inProgramFiles) {
                Write-Error "FAIL: VS Code is NOT in Program Files - may be user install"
                exit 1
              }
              Write-Host "PASS: VS Code confirmed in system context (Program Files)."
              Stop-Process -Name "Code" -Force -ErrorAction SilentlyContinue
              Start-Sleep -Seconds 2
              # VS Code spawns child processes - clean them up
              Get-Process -Name "Code" -ErrorAction SilentlyContinue | Stop-Process -Force
              Write-Host "VS Code smoke test passed."

Step 3: (Optional) Create a Systems Manager Parameter Store

 AWS Systems Manager Parameter Store  is a centralized configuration data store for named values called parameters. A parameter is any piece of data stored in the Parameter Store, such as a block of text, a list of names, an AMI ID, a license key, and so on. With Parameter Store, you can securely store, organize, and retrieve configuration data at a scale. We will be storing the base AMI ID in the Parameter Store and using it in our Image recipe.
  1. Open the  AWS Systems Manager console. 
  1. In the navigation pane, under Application Tools choose Parameter Store.
  1. Choose Create parameter.
  1. For Name, enter a hierarchy and a name. For example, enter /imagebuilder/winserver. Please make sure the parameter name starts with /imagebuilder.
  1. For Parameter tier choose either Standard or Advanced.
  1. For Type, choose String.
  1. For Data type, choose aws:ec2:image to hold the resource ID for an Amazon Machine Image (AMI).
  1. For Value, specify the base image AMI ID that you want to use to create a custom image. For example: ami-0dbf5ea29aEXAMPLE
  1. Choose Create parameter.
  1. Choose the parameter to view its details and note the ARN. You will need this for the next step.


Step 4: Create the image recipe

A recipe is the blueprint for your custom image. It tells Image Builder three things: which base image to start from (such as a Windows Server 2022 AMI), which build and test components to apply (the YAML documents we created earlier), and how the build instance should be configured (storage, working directory, and other parameters). Think of it as the complete instruction set that turns a stock Windows image into your organization's golden image.
  1. Open the  EC2 Image Builder console .
  1. In the left navigation, under Saved resources, choose Image Recipes.
  1. Choose Create image recipe.
  1. For Recipe name specify a name of your choice. For example: WorkSpaces-Custom-Apps-Recipe.
  1. Specify Version: 1.0.0.
  1. For Base image, choose Use custom AMI – updated.
  1. For AMI source, choose SSM parameter - Recommended and specify the SSM parameter ARN from the previous step.
  1. Under Components, in Build components, choose Add build components, and select Owned by me. From the selection panel on the right side of the console interface, select Install-Custom-Apps-NotepadPP-Chrome-VSCode. For versioning options, select Use latest version available. Choose Add to Recipe.
  1. For Test components, choose Add build components, and select Owned by me. From the selection panel on the right side of the console interface, select Test-Custom-Apps-NotepadPP-Chrome-VSCode. For versioning options, select Use latest version available. Choose Add to Recipe.
  1. Choose Create recipe.
Note: For the Base image, you can select the option based on the source of your base image.
  • Select managed images: Image Builder managed images created by you, shared with you, or provided by AWS.
  • AWS Marketplace images: Choose from images you subscribed to in AWS Marketplace.
  • Use custom AMI - updated: Use an SSM parameter for automatic base image updates, or enter a static AMI ID. The SSM Agent must be pre-installed in the selected AMI.
  • Import base image: Import from your VM into Image Builder and use the converted image as the base image in your recipe.

Step 5: Define the image creation process with Image Workflows

An  image workflow  controls what happens during each stage of the image creation process — build, test, and distribution. It's a YAML document that defines which steps run, in what order, and what to do if something fails (abort and roll back or mark the failure and keep going). You can use the  Amazon-managed workflows  out of the box for standard behavior or create your own when you need additional steps — like running Windows Update via SSM before your applications are installed.

The three workflow stages

Build workflow (BUILD) — Launches a build instance, waits for SSM agent readiness, runs your build components (installs our three apps), creates an AMI from the customized instance, and terminates the build instance.
Test workflow (TEST) — Launches a fresh instance from the new AMI, runs your test components (our smoke tests), collects results. If any test fails, the image is marked as failed, and nothing gets distributed.
Distribution workflow (DISTRIBUTION) — Optional. Copies the AMI to target Regions and applies sharing settings.
For this walkthrough, we’ll use the default distribution workflow and configure distribution settings separately.

Standard vs Express workflows

  1. Standard (default) — Full EC2 status checks, image metadata collection, thorough validation. Recommended for production golden images.
  1. Express — Stripped-down, faster builds. Skips metadata collection and uses faster instance checks. Great for rapid iteration during development.
For this article, we will create a custom build workflow.
  1. Open the  EC2 Image Builder console .
  1. In the left navigation, under Saved resources choose Image workflows.
  1. Choose Create image workflow.
  1. Under Image workflow type, choose Build.
  1. Under General, specify Image workflow name, Version and Description.
  1. Under Definition document, choose Start from scratch.
  1. Clear the existing content and copy-paste the YAML below into the Content editor.

Custom build image workflow YAML

YAML
name: custom-build-workflow-with-patching
description: Custom build workflow that patches Windows via AWS-RunPatchBaseline
             before running build components.
schemaVersion: 1.0

steps:

  # Step 1: Launch the build instance and wait for SSM agent

  - name: LaunchBuildInstance
    action: LaunchInstance
    timeoutSeconds: 7200
    onFailure: Abort
    inputs:
      waitFor: ssmAgent

  # Step 2: Run Windows Update using AWS-RunPatchBaseline
  # onFailure: Continue - if patching fails, we still want the image built.
  # The step will be marked FAILED.

  - name: RunWindowsUpdate
    description: "Runs AWS-RunPatchBaseline run command document with default patch basline defined in SSM Patch Manager"
    action: RunCommand
    onFailure: Continue
    timeoutSeconds: 5400
    inputs:
      documentName: AWS-RunPatchBaseline
      instanceId.$: $.stepOutputs.LaunchBuildInstance.instanceId
      parameters:
        Operation:
          - Install
        RebootOption:
          - RebootIfNeeded

  # Step 3: Run your custom build components (app installs, configs, etc.)

  - name: ApplyBuildComponents
    action: ExecuteComponents
    onFailure: Abort
    if:
       booleanEquals: true
       value: "$.imagebuilder.hasBuildComponents"
    inputs:
      instanceId.$: "$.stepOutputs.LaunchBuildInstance.instanceId"

  # Step 4: Run sysprep

  - name: RunSysPrepScript
    action: RunSysPrep
    onFailure: Abort
    if:
      and:
        - stringEquals: "AMI"
          value: "$.imagebuilder.imageType"
        - stringEquals: "Windows"
          value: "$.imagebuilder.platform"
    inputs:
      instanceId.$: "$.stepOutputs.LaunchBuildInstance.instanceId"

  # Step 5: Create the AMI from the customized instance

  - name: CreateOutputAMI
    action: CreateImage
    onFailure: Abort
    if:
      stringEquals: "AMI"
      value: "$.imagebuilder.imageType"
    inputs:
      instanceId.$: "$.stepOutputs.LaunchBuildInstance.instanceId"

  # Step 6: Terminate the build instance

  - name: TerminateBuildInstance
    action: TerminateInstance
    onFailure: Continue
    inputs:
      instanceId.$: $.stepOutputs.LaunchBuildInstance.instanceId

outputs:
  - name: "ImageId"
    value: "$.stepOutputs.CreateOutputAMI.imageId"
Similarly, you can create test and distribution image workflows using the Start from template or Start from scratch definition document options.
We created this custom build image workflow because the Amazon-managed workflow doesn't perform Windows OS updates. We are using the Systems Manager  Patch Manager  to perform Windows updates. Patch Manager uses a default patch baseline with  AWS-RunPatchBaseline  Run Command document to perform the updates. You can create your own  patch baseline  to use Patch Manager to perform the Windows OS updates. For the purposes of this article, we are downloading updates from the Windows Update Catalog. So, the build instance must have internet connectivity; otherwise, the Windows Update step will fail, and the workflow will proceed without patching.
Note: You will need to create a policy with below permission and add it EC2ImageBuilderExecutionRole role to run the AWS-RunPatchBaseline Run Command document.
JSON
{
	"Version": "2012-10-17",
	"Statement": [
        {
            "Sid": "SendCommandDocumentPermissions",
            "Effect": "Allow",
            "Action": [
                "ssm:SendCommand"
            ],
            "Resource": [
                "arn:aws:ssm:*:*:document/AWS-RunPatchBaseline"
            ]
        }
	]
}

What AWS-RunPatchBaseline does

AWS-RunPatchBaseline is a Systems Manager command document that scans or installs patches on managed instances based on a patch baseline. When you run it with the "Install" operation, it:
  1. Scans the instance against the applicable patch baseline (default or custom).
  1. Downloads and installs all missing patches that match the baseline’s approval rules.
  1. Reboots the instance if any patches require it (when RebootOption is set to RebootIfNeeded).
  1. Reports compliance status back to Systems Manager Patch Manager.

Step 6: Create an Infrastructure Configuration

An  infrastructure configuration  is a reusable Image Builder resource that defines the Amazon EC2 environment where Image Builder builds and tests your image. When you create an image pipeline, you attach one infrastructure configuration to it. Image Builder then uses those settings every time the pipeline runs a build.
  1. Open the  EC2 Image Builder console . 
  1. In the left navigation, under Saved resources, choose Infrastructure configurations. 
  1. Choose the Create infrastructure configuration from the right side. 
  1. Under General, specify Name and Description. For example, WorkSpaces-Image-Build-Infra-Config. 
  1. For the  IAM role , select a role that has a trust relationship with ec2.amazon.com and has the following policies attached: EC2InstanceProfileForImageBuilder, AmazonSSMManagedInstanceCore and AmazonS3ReadOnlyAccess. 
  1. Under AWS infrastructure, for Instance Type select an  instance type  that supports NitroTPM. For example, M7i or M7i-flex. 
  1. In VPC, subnet, and security groups select a VPC with private subnet with internet access and a security group that allows outbound internet traffic. Internet access is required for Windows Updates, downloading the software from vendor URL and reaching AWS service endpoints. 
  1. In Troubleshooting settings,
  • By default, the Terminate instance on failure check box is selected. Unselect the box to troubleshoot if a build fails. 
  • Specify or create a new Key pair to securely connect to the instance to troubleshoot if a build fails. 
  1. In Instance metadata settings, for metadata version select V2 (token required) 
  1. Choose the Create infrastructure configuration.

Step 7: (Optional) Create AMI distribution settings

Distribution settings define how and where your output Amazon Machine Images (AMIs) are copied, shared, and configured across different AWS regions and accounts. Since we are using the SSM Parameter Store to store the AMI ID, we may want to update the output AMI ID from the image pipeline to the SSM parameter store.
  1. Open the  EC2 Image Builder console . 
  1. In the left navigation, under Saved resources, choose Distribution settings. 
  1. Choose the Create distribution settings from the right side. 
  1. For Image type, select Amazon Machine Image (AMI). 
  1. Specify the Name and Description. 
  1. Under Region settings,  
  • In Region 1, the current region is specified by default. 
  • For KMS key, select Do not enable. WorkSpaces Personal, WorkSpaces Core Bundles and WorkSpaces Application do not support importing an encrypted AMI. 
  • For SSM parameter configurations, choose Add Parameter.
i. Specify the Parameter name. For example, /imagebuilder/workspacesimages/windows11. Please make sure the parameter name starts with /imagebuilder.
ii. For Data type, select AWS EC2 Image
  1. Choose Create settings.

Step 8: Create an Image Builder Image Pipeline

 Image pipelines  in EC2 Image Builder provide an automation framework for creating and maintaining custom AMIs and container images. With a pipeline, you can:
  • Assemble all the pieces for your image build — base image, components, infrastructure configuration, and distribution settings — in a single workflow.
  • Schedule automated builds using the console Schedule builder or cron expressions to keep your images current.
  • Skip unnecessary builds by detecting changes in your base image and components, so scheduled builds only run when something has changed.
  • Automate with Amazon EventBridge to trigger builds in response to events across your AWS environment.
  1. Open the  EC2 Image Builder console . 
  1. From the left navigation, choose Image pipelines. 
  1. For Pipeline name, specify a name. For example, WorkSpaces-Custom-Image-Pipeline 
  1. For Build schedule, select how you want to run the pipeline, on a specific schedule (On schedule or custom) or manually. 
  1. For Recipe, select the recipe created in Step 4 
  1. For Workflow, choose Select workflows. 
  • For Build workflow, select the workflow created in Step 5. 
  • For Test workflow, select test-image/x.x.x. 
  • For Distribution workflow, select the workflow created in Step 7, if you would like to update the base image in SSM parameter store, else leave it blank.
  1. For Infrastructure configurations, choose Select a configuration and select the configuration we created in Step 6.
  1. Under Execution role, for IAM role, choose Create new role with required permission. A window pops ups, choose Create Role on the window to create the execution role.
  1. Choose Create pipeline.

Step 9: Run the Image Pipeline

  1. Select pipeline > Actions > Run pipeline.
  1. The workflow engine orchestrates: Building → Testing → Distributing.
  1. To view the output image, choose the pipeline > Output images > Choose the Version (opens in new tab). Under Output resources, the AMI ID is shown.
This is the AMI you will import into WorkSpaces.
Note: Expect the full run to take about 45–60 minutes for a Windows build with three app installs. Most of that time is OS patching (if you included the update-windows component) and the reboot cycle. The duration of the pipeline will vary based on the configurations you are applying and the tests that you are performing on the image.

Step 10: Import your AMI into the WorkSpaces

Now that you have a final output image, it's time to import the image into the WorkSpaces service you are using.

Importing Your Windows 11 BYOL AMI into WorkSpaces Personal and WorkSpaces Core Bundles

This steps assumes that you already have BYOL enabled for your account. See  Bring Your Own Windows desktop licenses in WorkSpaces . Once BYOL is enabled, you can import the image.
  1. In the  WorkSpaces console , navigate to Images.
  1. In the left navigation pane, choose Images and then choose Import Image
  1. Under Base Image Options select AMI Import.
  1. Under Use AMI > AMI ID choose the output AMI ID from Step 9.
  1. For Infrastructure Configuration, choose either Use an existing configuration or Create Infrastructure configuration using service defaults. You can also create your own configuration by following Step 6 and then choose it.
  1. Under Image details, provide the following: Image Name, Compute Type, OS Version. For Protocol select DCV for WorkSpaces Personal or BYOP for WorkSpaces Core Bundles.
  1. Choose Import Image.
Once the image import completes, pair it with a hardware configuration (compute type and storage) to create a custom bundle. This bundle is what you use to create WorkSpaces for your end users.

Importing Your AMI into WorkSpaces applications

WorkSpaces Applications supports image import for Windows 11 BYOL, Windows Server 2022 and 2025. Before importing a BYOL image, ensure BYOL is enabled for your account. See  Bring Your Own Windows Desktop Licenses for Amazon WorkSpaces Applications .
  1. Open the  WorkSpaces Applications console .
  1. In the left navigation pane, choose Images and then choose Image registry.
  1. Choose Import Image.
  1. Image source - choose
  • AMI ID (Windows Server OS Only) - choose the output AMI ID from Step 9
  • Amazon WorkSpaces Image (Windows 11 BYOL and Windows Server) - Enter a WorkSpaces Image ID (starts with "wsi-").
Note: For importing Windows 11 BYOL image into WorkSpaces Applications, we first need to import that image into WorkSpaces Personal. We performed these steps in Importing Your Windows 11 BYOL AMI into WorkSpaces Personal and WorkSpaces Core Bundles section.
  1. Under Details specify an Image Name.
  1. (Optional) For Applications catalog and launch performance manifest
  • Application catalog: To create an application catalog specify details about the applications installed your image. For each application that you plan to stream, you can specify the name, display name, executable file to launch, and icon to display.
  • Launch performance: Adding files to the application optimization manifest reduces the time that it takes for the application to launch for the first time on a new fleet instance. The optimization manifest is a line-delimited text file that is per application.
Plain text
[
  {
    "Name": "NotepadPP",
    "DisplayName": "Notepad Plus Plus",
    "AbsoluteAppPath": "C:\\Program Files\\Notepad++\\notepad++.exe",
    "WorkingDirectory": "C:\\Program Files\\Notepad++"
  },
  {
    "Name": "GoogleChrome",
    "DisplayName": "Google Chrome",
    "AbsoluteAppPath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
    "WorkingDirectory": "C:\\Program Files\\Google\\Chrome\\Application"
  },
  {
    "Name": "VisualStudioCode",
    "DisplayName": "Visual Studio Code",
    "AbsoluteAppPath": "C:\\Program Files\\Microsoft VS Code\\Code.exe",
    "WorkingDirectory": "C:\\Program Files\\Microsoft VS Code"
  }
]
  1. Choose Import Image.
Note: Adding Applications catalog and launch performance manifest details obviate the need to launch an image builder and run the Image Assistant wizard to create a custom image with published applications. You may still need to follow the image builder process if you want to add any customizations that you want to make available to your end users.
Once the image import complete, you can create a fleet from that image.

Importing Your AMI into WorkSpaces Core Managed Instances

The output AMIs created by EC2 Image Builder pipeline are available in EC2 service. Third-party technology partners like Citrix, WorkSpot, LeoStream and Dizzion that integrates with WorkSpaces Core Managed Instances uses these AMIs to create the virtual desktop infrastructure (VDI) instances in EC2. Based on which technology partner solution you are using, refer to their respective documentation to install the agent on the output AMIs and use the AMIs to create the VDI instances. No separate import step is required — the AMI is already in EC2 where Managed Instances expect it.

Wrapping it Up - One Pipeline, Four Destinations

That’s it — you now have a fully automated pipeline that builds, tests, and distributes custom Windows images for the Amazon WorkSpaces. No more monthly manual runbooks, no more hoping that last week’s image was built the same way as this week’s.
The pipeline you built today can be triggered manually when you need it, or left on a schedule to quietly do its job in the background. Every run produces the same result: a consistent, tested, documented image ready for production. That’s the kind of operational reliability that frees you up to work on things that actually need a human brain.
The YAML components we walked through are a starting point. Swap in your own applications, add more test validations, chain in additional components for security hardening or compliance tooling. The framework scales with you. You can even automate this with event-driven architecture that runs the pipeline on an event.
If you haven’t already, go build your first pipeline. The services are live in your account today, and you now have working component YAML.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article