Skip to main content
Image generation is the final stage of the build system, where packages are composed into bootable disk images or ISO installers based on configuration files.

​
Image Generation Overview

The image generation process transforms packages into usable outputs:

Configuration

JSON files define partitions, packages, and settings

Composition

Install packages into a filesystem

Formatting

Convert to VHD, VHDX, ISO, or other formats

​
Complete Image Build Flow

​
Configuration Files

Image generation is entirely driven by configuration files that define:
  • Image format - VHD, VHDX, ISO, container, etc.
  • Disk layout - Partition sizes, filesystems, mount points
  • Boot configuration - Bootloader, kernel parameters, UEFI/BIOS
  • Package composition - Which packages to install
  • Customization - Users, services, files, scripts
For complete configuration file format documentation, see Image Configuration.

​
Default Image Configurations

The toolkit includes several pre-built configurations in ./imageconfigs/:
Gen-2 Hyper-V compatible
  • Creates core.vhdx image
  • UEFI boot support
  • Basic system with essential packages
  • Default for most builds
make image
# Uses ./imageconfigs/core-efi.json by default

​
Stage 1: Configuration Validation

The imageconfigvalidator tool validates configuration files before any build work begins.

​
What Gets Validated

  • Valid JSON syntax
  • Required fields present
  • Field types correct
  • No unknown fields
  • Partition sizes are valid
  • Partitions fit within disk size
  • Filesystem types are supported
  • Mount points are valid
  • Package names are valid
  • No conflicting packages
  • Required packages present (kernel, bootloader, etc.)
  • Boot configuration is valid
  • Kernel parameters are reasonable
  • UEFI/BIOS settings consistent with partitioning
Run validation manually with:
imageconfigvalidator --input=myconfig.json

​
Stage 2: Package Resolution

The imagepkgfetcher tool gathers all packages needed for the image.

​
Package Sources

Similar to graphpkgfetcher, this tool searches multiple sources:
1

Local Built Packages

RPMs built during the build-packages stage in ./../out/RPMS/
2

Cached Packages

Previously downloaded packages in the RPM cache
3

Remote Repositories

Official Azure Linux package servers (unless DISABLE_UPSTREAM_REPOS=y)
4

Custom Repositories

Additional repos specified in REPO_LIST

​
Dependency Resolution

For each package listed in the config:
  1. Find the package in available sources
  2. Determine all runtime dependencies recursively
  3. Download missing packages from remote repos
  4. Cache all packages locally for image composition
Unlike package building, image generation only needs runtime dependencies. Build dependencies are not included in the final image.

​
Stage 3: Image Composition (Imager)

The imager tool creates the actual filesystem and installs packages using a chroot environment.

​
Image Composition Process

1

Create Disk Structure

  • Allocate raw disk image or directory
  • Create partition table (GPT or MBR)
  • Format partitions with specified filesystems
  • Set up mount points
2

Initialize Filesystem

  • Create basic directory structure (/etc, /usr, /var, etc.)
  • Set up device nodes (/dev)
  • Configure initial system files
3

Install Packages

  • Mount disk as loopback device (for raw images)
  • Use RPM to install packages into filesystem
  • Resolve dependencies and install in correct order
  • Run post-installation scripts
4

Configure System

  • Set up users and groups
  • Configure networking
  • Enable/disable services
  • Install custom files
  • Run custom scripts
5

Install Bootloader

  • Install GRUB or other bootloader
  • Generate boot configuration
  • Set up kernel and initramfs
  • Configure boot parameters
6

Finalize

  • Set file permissions
  • Create necessary symlinks
  • Unmount filesystems
  • Clean up temporary files

​
Raw Image vs Directory

The imager can produce two types of output:
Full disk image with partitions
  • Contains partition table
  • Bootloader installed in MBR/ESP
  • Mounted as loopback device during composition
  • Converted to final format by roast tool
Use for: VHDs, VHDXs, bootable ISOs
The imager uses the chroot worker environment to properly handle RPM installations and post-install scripts, ensuring packages are configured correctly for the target system.

​
Stage 4: Format Conversion (Roast)

The roast tool converts raw disk images into final output formats.

​
Supported Output Formats

VHD

Virtual Hard Disk
  • Hyper-V Gen-1 VMs
  • Azure (older)
  • Fixed or dynamic allocation

VHDX

Virtual Hard Disk v2
  • Hyper-V Gen-2 VMs
  • Azure (current)
  • Better performance and features

QCOW2

QEMU Copy-On-Write
  • KVM/QEMU virtual machines
  • OpenStack
  • Efficient storage

RAW

Raw Disk Image
  • Universal format
  • No overhead
  • Large file size

​
Conversion Process

# Roast takes a raw image and produces the final format
roast --input=image.raw --output=image.vhdx --format=vhdx
The conversion process:
  • Preserves partition layout and data
  • Converts bootloader as needed
  • Optimizes for target format
  • Validates output integrity

​
ISO Installer Builds

ISO builds are different from standard images—they create bootable installers that can deploy images to target computers.

​
ISO Components

RAM-based root filesystem
  • Boots from memory
  • Contains installer application
  • Includes necessary drivers and tools
  • Two versions available:
    • GUI: Calamares-based graphical installer
    • Terminal: Text-based installer

​
Building ISOs

The ISO build process:
1

Build Initrd

  • Uses a static configuration included with toolkit
  • Recursive Make call to build initrd image
  • Includes liveinstaller tool
  • Contains minimal package set for installation
2

Prepare Payload

  • Build or gather target image packages
  • Include configuration files
  • Compress installation data
3

Create ISO (isomaker)

  • Combine initrd, payload, and boot configuration
  • Create ISO 9660 filesystem
  • Make bootable for UEFI and BIOS
  • Generate checksum files
# Build ISO installer
make iso CONFIG_FILE=./imageconfigs/core-efi.json

# Or build with GUI installer (Calamares)
make iso CONFIG_FILE=./imageconfigs/core-efi.json INSTALLER_TYPE=gui
Building the initrd requires a recursive Make call with a different CONFIG_FILE. Since many build system components depend on CONFIG_FILE, rebuilding the initrd invalidates cached state and triggers a brief rebuild.This is expected behavior and ensures the initrd is built correctly for the target configuration.

​
Live Installer

The liveinstaller tool runs inside the ISO’s initrd and is responsible for:
  • Detecting target disks
  • Partitioning and formatting disks
  • Installing packages to target
  • Configuring bootloader
  • Applying customizations
  • Running post-install scripts
It provides a streamlined installation experience, whether GUI or terminal-based.

​
Distroless Images

Azure Linux supports distroless container images without an RPM database.

​
RPM Manifest File

Distroless images include /var/lib/rpmmanifest/container-manifest-2 containing the output of: 
rpm --query --all --query-format "%{NAME}\t%{VERSION}-%{RELEASE}\t%{INSTALLTIME}\t%{BUILDTIME}\t%{VENDOR}\t%{EPOCH}\t%{SIZE}\t%{ARCH}\t%{EPOCHNUM}\t%{SOURCERPM}\n" | grep -v gpg-pubkey
This allows Security Composition Analysis (SCA) tools to detect image contents without a full RPM database.
The manifest file provides package metadata for security scanning while keeping the image minimal by excluding the full RPM database.

​
Output Locations

Built images are placed in: 
./../out/images/
├── core.vhdx          # VHDX disk image
├── core.iso           # ISO installer
├── core.qcow2         # QEMU image
└── core-container.tar.gz  # Container image

​
Next Steps

Build Logs

Learn how to interpret and troubleshoot build errors

Package Building

Return to the package building process

Build docs developers (and LLMs) love

Get started for freeTalk to us