Skip to main content
Image configuration files define how Azure Linux images are built, including disk layout, partitions, system settings, and package lists. These JSON configuration files control the entire image generation process.

​
Configuration Structure

An image configuration consists of two main sections:

Disks

Defines disk layout, partitions, and artifacts

SystemConfigs

Defines system configuration, packages, and settings

​
Basic Configuration Example

Here’s a minimal EFI-based image configuration:
core-efi.json
{
    "Disks": [
        {
            "PartitionTableType": "gpt",
            "MaxSize": 4096,
            "Artifacts": [
                {
                    "Name": "core",
                    "Type": "vhdx"
                }
            ],
            "Partitions": [
                {
                    "ID": "boot",
                    "Flags": ["esp", "boot"],
                    "Start": 1,
                    "End": 9,
                    "FsType": "fat32"
                },
                {
                    "ID": "rootfs",
                    "Start": 9,
                    "End": 0,
                    "FsType": "ext4"
                }
            ]
        }
    ],
    "SystemConfigs": [
        {
            "Name": "Standard",
            "BootType": "efi",
            "PartitionSettings": [
                {
                    "ID": "boot",
                    "MountPoint": "/boot/efi",
                    "MountOptions": "umask=0077"
                },
                {
                    "ID": "rootfs",
                    "MountPoint": "/"
                }
            ],
            "PackageLists": [
                "packagelists/core-packages-image.json"
            ],
            "KernelOptions": {
                "default": "kernel"
            },
            "Hostname": "azurelinux"
        }
    ]
}

​
Configuration Sections

​
Disks Section

The Disks array defines the physical disk layout:
  • Partition table type (GPT or MBR)
  • Disk size for virtual disks
  • Partitions with filesystem types and sizes
  • Artifacts defining output image format

​
SystemConfigs Section

The SystemConfigs array defines system-level configuration:
  • Boot configuration (EFI or legacy)
  • Partition mounting and mount options
  • Package lists to install
  • Kernel options and command line parameters
  • Users and network configuration
  • Customization scripts for pre/post-install

​
Configuration Validation

Validate your image configuration using the imageconfigvalidator tool: 
imageconfigvalidator --config myconfig.json

​
Common Use Cases

Virtual Machines

VHDX/VHD images with EFI or legacy boot

Container Images

Rootfs-only images without partitions

ISO Installers

Bootable installation media

Cloud Images

Marketplace images with cloud-init

​
Next Steps

Disk Configuration

Learn about disk and partition configuration

System Configuration

Configure system settings and packages

Package Lists

Manage package lists and dependencies

Examples

View real-world configuration examples

Build docs developers (and LLMs) love

Get started for freeTalk to us