GitHub
Sign in
Start for free
View Categories

Image Definitions

Quick Guide #

This is the final step of creating images. If you have not yet configured your Connection, Operating Systems, Builder Configuration or Provisioner Role, please do so before proceeding.

Create a new Image Definition #

1. In the upper-right corner, click + New Image.
2. Enter all required parameters and click Save.
3. Right-click the newly created Image Definition and select Run to create the images.

Update an existing Image Definition #

1. Right-click the Image Definition and select Details.
2. Adjust the parameters as needed and click Save.
3. Run the Image Definition to create a new image version with the updated configuration.

Delete an Image Definition #

1. To delete an Image Definition, right-click it and select Delete.
2. This removes the Image Definition from XOAP, but all previously created image versions remain in your environment.

Additional useful information #

• The Connector in an Image Definition is required for secure deployments in both cloud and on-premises environments. See our documentation for instructions on how to deploy the XOAP Connector on your machine.
• We provide example Builder Configurations, Operating Systems, and Provisioner Roles in your Workspace as quick-start templates. They may not fully match your environment, so feel free to modify them or create your own.
• To view the log for the last run, click on the Status badge. Live logging and stopping an image run can be done from the Runs view.
• If a run is stopped, the temporary files created during that run are not deleted from your environment. For Failed or Succeeded runs, temporary files are removed automatically.

Technical documentation #

General #

The image definition is the final and most crucial step in the image creation process. This is where you bring together all previously configured components—Provisioner Role, Operating System, and Builder Configuration—into a single, unified blueprint.

By combining these elements, you define exactly how the virtual machine image will be built, what operating system it will use, how it will be configured, and in which environment it will be deployed (e.g., AWS, Azure, etc.).

In XOAP, this step ensures that your image is consistently created according to your selected setup and ready for deployment or automation.

The interface allows you to:

• Assign a name and description to the image definition
• Select tags for categorization or filtering
• Choose the builder provider and specific builder configuration
• Pick a base operating system image
• Link the appropriate provisioner role (which includes all scripts, tasks, and configurations)
• Define a XOAP Connector device for on-premises Image definitions or secure cloud environments
• Schedule Image Definition Run

Run or schedule image builds #

By runing an Image Definition you will start the image build process. You can track the progress by clicking the Runs button in the upper right corner. This opens a side panel showing active runs.

By clicking Toggle Logs, you can follow live build logs and monitor progress in real time.

There are several possible statuses for an image definition run:

No Runs – The image definition has not been executed yet
Queued – The run is waiting in line and will start when resources are available
Running – The image build process is currently in progress
Succeeded – The image was successfully built and completed without errors
Failed – The image build process encountered an error and did not complete
Stopped – The image build was successfully stopped by a user and did not complete

The Image Definition run can take anywhere from a few minutes to a few hours.

This mainly depends on the number of provisioners being used and the selected base operating system. If you want to see more details about a specific image definition, click Details in the Action menu.

For Windows Image Definitions in cloud environments the sysprep command is executed automatically at the end of the image definition run. For on-premises environments you need to add it manually inside your Provisioner Role.

Sysprep provisioners which we are running as PowerShell script automatically on cloud can be found on our GitHub repo: https://github.com/xoap-io/xoap-packer-templates.

And below is example of script which you can use for sysprep on on-premises image definitions. To use it, upload a script to resource area, then assign script provisioner on last place in your definition.


<#
.SYNOPSIS
    Performs final cleanup and prepares Windows Server 2025 for sysprep

.DESCRIPTION
    This script performs final cleanup tasks and prepares the system for sysprep and imaging on Windows Server 2025.
    Developed and optimized for use with the XOAP Image Management module, but can be used independently.
    No liability is assumed for the function, use, or consequences of this freely available script.
    PowerShell is a product of Microsoft Corporation. XOAP is a product of RIS AG. © RIS AG

.COMPONENT
    PowerShell

.LINK
    https://github.com/xoap-io/xoap-packer-templates

#>

Set-StrictMode -Version Latest
$ProgressPreference = 'SilentlyContinue'
$ErrorActionPreference = 'Stop'

# Setup local file logging to C:\xoap-logs
try {
    $LogDir = 'C:\xoap-logs'
    if (-not (Test-Path $LogDir)) {
        New-Item -Path $LogDir -ItemType Directory -Force | Out-Null
    }
    
    $scriptName = [IO.Path]::GetFileNameWithoutExtension($PSCommandPath)
    $timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
    $LogFile = Join-Path $LogDir "$scriptName-$timestamp.log"
    
    Start-Transcript -Path $LogFile -Append | Out-Null
    Write-Host "Logging to: $LogFile"
} catch {
    Write-Warning "Failed to start transcript logging to C:\xoap-logs: $($_.Exception.Message)"
}

# Simple logging function
function Write-Log {
    param($Message)
    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
    Write-Host "[$timestamp] $Message"
}

trap {
    Write-Log "ERROR: $_"
    Write-Log "ERROR: $($_.ScriptStackTrace)"
    Write-Log "ERROR EXCEPTION: $($_.Exception.ToString())"
    try { Stop-Transcript | Out-Null } catch {}
    Exit 1
}

try {
    Write-Log 'Starting final cleanup and sysprep'
     
    # Defragment system drive
    Write-Log 'Optimizing system drive...'
    try {
        Optimize-Volume -DriveLetter C -Defrag -Verbose:$false
        Write-Log 'System drive optimization completed'
    } catch {
        Write-Log "Warning: Could not optimize system drive: $($_.Exception.Message)"
    }
    
    Write-Log 'Final cleanup completed, preparing for sysprep...'
      
    # Stop transcript before sysprep
    try { Stop-Transcript | Out-Null } catch {}
    
    # Prepare sysprep command
    $sysprepPath = Join-Path $env:WINDIR "System32\Sysprep\sysprep.exe"
    $sysprepArgs = @('/generalize', '/oobe')
    
    Write-Log "Running sysprep with arguments: $($sysprepArgs -join ' ')"
    Write-Log "This will shutdown the system when complete"
    
        # Check if sysprep.exe exists
        if (Test-Path $sysprepPath) {
            # Run sysprep using Start-Process for better error handling
            $process = Start-Process -FilePath $sysprepPath -ArgumentList $sysprepArgs -Wait -PassThru
            $exitCode = $process.ExitCode
            if ($null -eq $exitCode) {
                # Fallback to $LASTEXITCODE if ExitCode is not set
                $exitCode = $LASTEXITCODE
            }
            if ($exitCode -ne 0) {
                Write-Log "Sysprep failed with exit code: $exitCode"
                exit $exitCode
            }
        } else {
            Write-Log "Sysprep executable not found at $sysprepPath"
            exit 1
        }
    
} catch {
    Write-Log "Critical error in final cleanup: $($_.Exception.Message)"
    try { Stop-Transcript | Out-Null } catch {}
    throw
}

Scheduling Image Definition runs provides several operational and strategic advantages. By automating the execution of image builds at defined intervals, you eliminate the need for manual intervention and reduce the risk of human error.

Scheduled runs help maintain consistency across environments by ensuring that the latest configurations and software updates are regularly incorporated into your images. This is especially important for compliance and security, as it guarantees that patched and up-to-date images are always available.

Additionally, scheduling builds during off-peak hours can optimize resource usage and avoid impacting other workloads. Finally, regularly scheduled images improve preparedness for disaster recovery scenarios by ensuring that clean and current machine images are readily accessible.

There are two ways to schedule image definition runs:

1. By creating a new schedule
2. By editing an existing schedule

To manage either option, navigate to the Schedules section.
If you want to create a new schedule, click the New Schedule button in the upper right corner. In the first step, provide a name and define schedule parameters (e.g., frequency, start time). In the second step, select the image definitions you want to assign to this schedule. One image definition can be linked to multiple schedules.

If you wish to assign an image definition to an existing schedule, select the desired schedule from the list, click the three-dot menu, and then choose Details. In the details view, select the image definitions you want to include and click Save.

Locate your created image on your hypervisior or hyperscaler #

Once a run finishes successfully, the created image is available in your environment. Images use the name defined in the Image Definition, with a version suffix added for each run. For example, if your Image Definition is named Windows11-BaseImage, the runs will create images such as Windows11-BaseImage-v1, Windows11-BaseImage-v2, and so on. If the image build fails, no image is created. The exact method for locating the image depends on your target environment.

Microsoft Azure #

The location of images created in Azure using XOAP Image Management depends on the selected Builder Type during builder creation. In the builder configuration, you can choose between Azure Managed and Azure Gallery.

  1. Azure Managed (Managed Images)
    If the selected builder type is Azure Managed, the image will be created as a standard Managed Image.
    • Location:
    Azure Portal → Images
    • Behavior:
    The image is stored regionally and is only available in the region it was created.
    • Use Case:
    This approach is recommended for simple deployments, testing, or proof-of-concept scenarios.
  2. Azure Gallery (Shared Image Gallery)
    If the selected builder type is Azure Gallery, the image will be stored in a Shared Image Gallery (SIG).
    • Location:
    Azure Portal → Shared Image Gallery
    • Behavior:
    The image supports versioning, can be replicated across multiple regions, and is scalable for enterprise scenarios.
    • Use Case:
    Best suited for production workloads or environments requiring regional redundancy and image lifecycle management.

Amazon Web Services (AWS) #

Images created via XOAP are stored as AMIs (Amazon Machine Images).

To locate:

1. Go to the AWS Console.
2. Navigate to EC2 → AMIs (under Images in the left menu).
3. Make sure to change the filter from Owned by Amazon to Owned by me.
4. Search using the AMI ID or name returned by the XOAP image definition run (e.g., ami-xxxxxxxxxxxxxxxxx).

By default, AMIs are private — they are only visible to the account that created them.
To make an AMI accessible from a different AWS account, you need to share it explicitly.
Follow these steps on the account where the AMI was created:

1. Open EC2 → AMIs (in the region where the AMI was created, e.g., eu-central-1).
2. Locate the AMI (e.g., ami-0839804dea557cd2b).
3. Select the AMI and click Actions → Modify Image Permissions.
4. Add the AWS Account ID of the recipient account.
5. Click Save.

Once shared, the AMI will be visible under the “Private Images” filter in the recipient’s EC2 dashboard.

Google Cloud Platform (GCP) #

XOAP images on GCP are stored under Compute Engine → Images.

To locate:

1. Go to the Google Cloud Console.
2. Navigate to Compute Engine → Images.
3. Filter by project or use the search bar to locate the image name generated by XOAP.
4. Custom images may be grouped by image families or individual entries depending on how the build was configured

Troubleshoot image builds or run failures #

When creating an image using XOAP Image Management, issues can typically arise from one of the following three areas:

1. Connections – Incorrectly configured cloud connection (e.g., invalid credentials or missing permissions).
2. Provisioners – Wrongly selected or misconfigured provisioners, such as scripts or tools that fail during execution.
3. Builder Configuration – Misconfigured builder parameters (e.g., invalid region, missing image settings).

All three types of issues are reflected in the logs of the image definition run.

To quickly identify the problem:

• Navigate to the Image Definitions table.
• Click on Status (Latest Run) for the corresponding image definition.
• A side panel will appear, showing the log of the latest run.
• Review the log to locate the error line and take the necessary corrective action.

Reviewing these logs is the most efficient way to debug failures and ensure your image builds succeed.

For logs from previous runs, click the three-dot menu next to the image definition and select Details. Scroll down to the Past Runs section and click the status of the desired run to view its log.

During the image build process, it’s possible to identify and troubleshoot issues in real time. Active image builds are visible in the Runs section, located in the upper-right corner of the Image Definitions page.

To monitor the ongoing process:

• Click on the log icon beside the image build to open the live log view.
• Logs are streamed in real time, with the latest entries appearing at the top.

This allows you to:

• Track provisioning steps as they occur.
• Quickly identify long-running provisioners that may cause timeouts.
• Take corrective actions early, potentially saving significant time during debugging and validation.

This view is especially useful for diagnosing failures without waiting for the entire build to complete.

On on-prem image build VMs, logs are typically stored locally in these common locations:

â—‹ Temporary folders: C:\Windows\Temp and %TEMP% (e.g., C:\Users\\AppData\Local\Temp)
â—‹ Windows troubleshooting logs (useful for install/update/sysprep issues):
â—‹ Event Viewer: Application and System
â—‹ C:\Windows\Logs\DISM\dism.log and C:\Windows\Logs\CBS\CBS.log
â—‹ Sysprep: C:\Windows\System32\Sysprep\Panther\setupact.log and setuperr.log

If you can’t find them, the most common reason is that the build VM is automatically cleaned up after the run (including on failure), so the local logs are deleted with it.

Tip: If you stop the run, the temporary build VM is not deleted, so you can connect to it and collect the logs for troubleshooting. After you finish investigating, remember to delete the temporary build VM to avoid leaving unused resources behind.

Common image build issues and how to resolve them #

1.Incompatible Provisioners – Using Linux provisioners on a Windows-based image (or vice versa) will cause failures. Resolution: Check the Provisioner Groups assigned to the selected role and remove any that are not relevant to the operating system of the image.

2. Invalid Credentials or Connection Settings – Connection issues may occur if the credentials are incorrect or the user lacks sufficient permissions. Resolution: Review your connection configuration under the Connections section. Ensure credentials are valid and have appropriate access rights.

3. Incorrect Builder Configuration – Errors may arise if the builder configuration references non-existent resources such as a virtual network or resource group. Resolution: Verify all values in the builder settings, especially network and resource group names.

4. Deprecated Operating System Definition – Older image definitions may reference deprecated or outdated operating systems. Resolution: Navigate to Operating Systems and add the latest version. Then, in the Image Definition details, update the OS selection from the dropdown to the newest version.

Powered by BetterDocs

Scroll to Top