Prepare an Ubuntu virtual machine for Azure

Applies to: ✔️ Linux VMs ✔️ Flexible scale sets

Ubuntu provides official Azure-ready cloud images (cloudimg) that include all components required for successful provisioning on Azure, such as cloud-init, Azure-optimized kernels, Azure guest agent compatibility, and performance-tuned defaults for virtualized environments. These images are the recommended starting point when creating a custom VHD because they align with Azure VM provisioning requirements and reduce the manual configuration steps required.

Ubuntu publishes these images in multiple formats, including ready-to-use Azure virtual hard disks (VHDs), on the https://cloud-images.ubuntu.com/ website. If you need to build a specialized Ubuntu image for Azure, you can start with these validated VHD builds and customize them as needed. The latest image releases are available at the following locations:

Ubuntu 20.04/Focal: focal-server-cloudimg-amd64-azure.vhd.tar.gz
Ubuntu 22.04/Jammy: jammy-server-cloudimg-amd64-azure.vhd.tar.gz
Ubuntu 24.04/Noble: noble-server-cloudimg-amd64-azure.vhd.tar.gz

Prerequisites

This article assumes that you've already installed an Ubuntu Linux operating system (OS) to a VHD. Multiple tools exist to create .vhd files. An example is a virtualization solution such as Hyper-V. For instructions, see Install the Hyper-V role and configure a virtual machine (VM).

Ubuntu installation notes

Important

The remote NVMe preparation step in this article is optional. Complete it only if you're creating an image that you intend to deploy with a remote NVMe disk controller. If the target VM uses SCSI, skip the remote NVMe step and retain the standard settings. Remote NVMe requires a Gen2 image. Verify that the Ubuntu release is listed in Supported OS images for remote NVMe and that the exact target VM size advertises NVMe in its DiskControllerTypes capability.

For more tips on preparing Linux for Azure, see General Linux installation notes.
The VHDX format isn't supported in Azure, only fixed VHD. You can convert the disk to VHD format by using Hyper-V Manager or the Convert-VHD cmdlet.
When you install the Linux system, we recommend that you use standard partitions rather than Logical Volume Manager (LVM), which is often the default for many installations. These standard partitions avoid LVM name conflicts with cloned VMs, particularly if an OS disk ever needs to be attached to another VM for troubleshooting. LVM or RAID can also be used on data disks.
Don't configure a swap partition or swap file on the OS disk. You can configure the cloud-init provisioning agent to create a swap file or a swap partition on the temporary resource disk. For more information about this process, see Create a SWAP partition for an Azure Linux VM.
All VHDs on Azure must have a virtual size aligned to 1 MB. When you convert from a raw disk to VHD, you must ensure that the raw disk size is a multiple of 1 MB before conversion. For more information, see Linux installation notes.

Important

Swap guidance that uses the temporary resource disk applies only to VM sizes that include local temporary storage. The remote disk controller type, SCSI or NVMe, doesn't determine whether a resource disk is available.

You can upload a prebuilt Ubuntu image directly to Azure and use the resulting VHD to create new virtual machines. If this is your first time uploading a .vhd file, see Create a Linux VM from a custom disk.

Manual steps

Note

Before you attempt to create your own custom Ubuntu image for Azure, consider using the prebuilt and tested images from the Ubuntu Cloud Images webpage instead.

If you are using Windows to Extract the prebuilt it image , please use Windows WSL and run the following command

     sudo tar --sparse -xvzf <image name>-azure.vhd.tar.gz

In the center pane of Hyper-V Manager, select the VM.
Select Connect to open the window for the VM.

Replace the current repositories in the image to use Ubuntu's Azure repository.

Before you edit /etc/apt/sources.list /etc/apt/sources.list.d/ubuntu.sources, we recommend that you make a backup:

For Ubuntu 22.04 and earlier

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

For Ubuntu 24.04 and later

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak

For Ubuntu 22.04 and earlier

sudo sed -i 's#http://archive\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list
sudo sed -i 's#http://[a-z][a-z]\.archive\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list
sudo sed -i 's#http://security\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list
sudo sed -i 's#http://[a-z][a-z]\.security\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list
sudo apt update

For Ubuntu 24.04 and later

sudo sed -i 's#http://archive\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's#http://[a-z][a-z]\.archive\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's#http://security\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's#http://[a-z][a-z]\.security\.ubuntu\.com/ubuntu#http://azure\.archive\.ubuntu\.com/ubuntu#g' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

The Ubuntu Azure images use Azure-Tailored Kernels Azure-tailored kernel. Update the OS to the latest Azure-tailored kernel and install Azure Linux tools (including Hyper-V dependencies):

sudo apt update
sudo apt install linux-azure linux-image-azure linux-headers-azure linux-tools-common linux-cloud-tools-common linux-tools-azure linux-cloud-tools-azure
sudo apt full-upgrade
sudo reboot

Modify the kernel boot line for GRUB to include extra kernel parameters for Azure. To do this step, open /etc/default/grub in a text editor, find the variable called GRUB_CMDLINE_LINUX_DEFAULT (or add it if needed), and edit it to include the following parameters:
```
    GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0,115200n8 earlyprintk=ttyS0,115200 rootdelay=300 quiet splash"
```
Save and close this file, and then run sudo update-grub. This step ensures that all console messages are sent to the first serial port, which can assist Azure technical support with debugging issues.
Only if you're creating an image for a remote NVMe disk controller, configure and verify NVMe boot support. Otherwise, skip this step.
1. Make the NVMe drivers persistent so they're added to every future initramfs, and then rebuild the current initramfs. The loop skips modules that are already listed, which avoids duplicate entries:
```
for module in nvme nvme_core; do
  grep -qxF "$module" /etc/initramfs-tools/modules || echo "$module" | sudo tee -a /etc/initramfs-tools/modules
done
sudo update-initramfs -u -k all
```
2. Add the Azure NVMe I/O timeout to the kernel command line, and then rebuild the GRUB configuration so the setting persists across reboots:
```
sudo sed -i '/^GRUB_CMDLINE_LINUX_DEFAULT=/ s/"$/ nvme_core.io_timeout=240"/' /etc/default/grub
sudo update-grub
```
3. Confirm that both NVMe modules exist in the kernel's module tree so they can be packaged into initramfs. This check reads the on-disk module files, so it succeeds even on a SCSI preparation VM and doesn't imply that NVMe is loaded or in use:
```
modinfo nvme
modinfo nvme_core
```
  Each command must return module details. If either module isn't found, install or enable it by following the Ubuntu kernel documentation before you continue.
Confirm that the rebuilt initramfs package includes both NVMe drivers. This check confirms the image is ready:
```
sudo lsinitramfs /boot/initrd.img-$(uname -r) | grep -E 'nvme(_core)?\.ko'
```
The output must list both the nvme and nvme_core drivers. After the image boots on an NVMe VM, verify the runtime timeout by running cat /sys/module/nvme_core/parameters/io_timeout; the expected value is 240.
For both SCSI and NVMe images, use file-system UUIDs or another persistent identifier in /etc/fstab. Don't use /dev/sd* or /dev/nvme* device names, because device names can change across reboots or when the disk controller changes.
1. List the block devices and their persistent identifiers so that you can compare them with the entries in /etc/fstab:
```
sudo blkid
```
2. Check /etc/fstab for syntax errors, invalid mount options, and references that can't be resolved:
```
sudo findmnt --verify --verbose
```
Ensure that the SSH server is installed and configured to start at boot time. This setting is usually the default.
Install cloud-init (the provisioning agent) and the Azure Linux agent (the guest extensions handler). Cloud-init uses netplan to configure the system network configuration (during provisioning and each subsequent boot) and gdisk to partition resource disks.
```
sudo apt update
sudo apt install cloud-init gdisk netplan.io walinuxagent && systemctl stop walinuxagent
```
Note

The walinuxagent package might remove the NetworkManager and NetworkManager-gnome packages, if they're installed.

Remove cloud-init default configurations and leftover netplan artifacts that might conflict with cloud-init provisioning on Azure: For Ubuntu 22.04 and earlier

sudo rm -f /etc/cloud/cloud.cfg.d/50-curtin-networking.cfg /etc/cloud/cloud.cfg.d/curtin-preserve-sources.cfg /etc/cloud/cloud.cfg.d/99-installer.cfg /etc/cloud/cloud.cfg.d/subiquity-disable-cloudinit-networking.cfg
sudo rm -f /etc/cloud/ds-identify.cfg
sudo rm -f /etc/netplan/*.yaml

For Ubuntu 24.04 and later

sudo rm -f /etc/cloud/cloud.cfg.d/curtin-preserve-sources.cfg /etc/cloud/cloud.cfg.d/99-installer.cfg /etc/cloud/cloud.cfg.d/subiquity-disable-cloudinit-networking.cfg
sudo rm -f /etc/cloud/ds-identify.cfg
sudo rm -f /etc/netplan/*.yaml

Configure cloud-init to provision the system by using the Azure data source:

sudo tee /etc/cloud/cloud.cfg.d/90_dpkg.cfg <<EOF
datasource_list: [ Azure ]
EOF

sudo tee /etc/cloud/cloud.cfg.d/90-azure.cfg <<EOF
system_info:
   package_mirrors:
     - arches: [i386, amd64]
       failsafe:
         primary: http://archive.ubuntu.com/ubuntu
         security: http://security.ubuntu.com/ubuntu
       search:
         primary:
           - http://azure.archive.ubuntu.com/ubuntu/
         security: []
     - arches: [armhf, armel, default]
       failsafe:
         primary: http://ports.ubuntu.com/ubuntu-ports
         security: http://ports.ubuntu.com/ubuntu-ports
EOF

sudo tee /etc/cloud/cloud.cfg.d/10-azure-kvp.cfg <<EOF
reporting:
  logging:
    type: log
  telemetry:
    type: hyperv
EOF

Configure the Azure Linux agent to rely on cloud-init to perform provisioning. For more information on these options, look at the WALinuxAgent project.

sudo sed -i 's/Provisioning.Enabled=y/Provisioning.Enabled=n/g' /etc/waagent.conf
sudo sed -i 's/Provisioning.UseCloudInit=n/Provisioning.UseCloudInit=y/g' /etc/waagent.conf
sudo sed -i 's/ResourceDisk.Format=y/ResourceDisk.Format=n/g' /etc/waagent.conf
sudo sed -i 's/ResourceDisk.EnableSwap=y/ResourceDisk.EnableSwap=n/g' /etc/waagent.conf

sudo tee -a /etc/waagent.conf <<EOF
# For Azure Linux agent version >= 2.2.45, this is the option to configure,
# enable, or disable the provisioning behavior of the Linux agent.
# Accepted values are auto (default), waagent, cloud-init, or disabled.
# A value of auto means that the agent will rely on cloud-init to handle
# provisioning if it is installed and enabled, which in this case it will.
Provisioning.Agent=auto
EOF

Clean cloud-init and Azure Linux agent runtime artifacts and logs:

sudo cloud-init clean --logs --seed
sudo rm -rf /var/lib/cloud/
sudo systemctl stop walinuxagent.service
sudo rm -rf /var/lib/waagent/
sudo rm -f /var/log/waagent.log

Deprovision the VM and prepare it for provisioning on Azure.

Note

The sudo waagent -force -deprovision+user command generalizes the image by attempting to clean the system and make it suitable for reprovisioning. The +user option deletes the last provisioned user account and associated data.
```
sudo waagent -force -deprovision+user
sudo rm -f ~/.bash_history
```
Warning

Deprovisioning by using the preceding command doesn't guarantee that the image is cleared of all sensitive information and is suitable for redistribution.
Select Action > Shut Down in Hyper-V Manager.
Azure only accepts fixed-size VHDs. If the VM's OS disk isn't a fixed-size VHD, use the Convert-VHD PowerShell cmdlet and specify the -VHDType Fixed option. For more information, look at the docs for Convert-VHD at Convert-VHD.
To bring a Generation 2 VM on Azure, create the fallback UEFI boot path:
1. Copy the ubuntu EFI directory to a new directory named boot:
```
sudo cp -rp /boot/efi/EFI/ubuntu /boot/efi/EFI/boot
```
2. Rename the EFI loader to the fallback boot loader name:
```
sudo mv /boot/efi/EFI/boot/shimx64.efi /boot/efi/EFI/boot/bootx64.efi
```
3. Rename the GRUB configuration file to the fallback name:
```
sudo mv /boot/efi/EFI/boot/grub.cfg /boot/efi/EFI/boot/bootx64.cfg
```

You're now ready to use your Ubuntu Linux VHD to create new VMs in Azure. If this is the first time that you're uploading the .vhd file to Azure, see Create a Linux VM from a custom disk.

For an existing Azure VM that you need to move from SCSI to NVMe, use Convert Linux and Windows VMs from SCSI to NVMe. For architecture and support information, see NVMe overview.

คำติชม

หน้านี้มีประโยชน์หรือไม่

Last updated on 2026-09-09

Prepare an Ubuntu virtual machine for Azure

Prerequisites

Ubuntu installation notes

Manual steps

Related content

คำติชม

แหล่งทรัพยากรเพิ่มเติม