Mohammad Jalloul's Blog

Azure loves Linux.

I know this sounds like a cliché… In fact, Microsoft Azure provides several Linux on Azure-Endorsed Distributions. However, for folks moving from an on-premises installation or even one residing in a private cloud setup, there is a reasonable chance that the Linux flavor and version that you have installed might not fall within any of the buckets of Azure-endorsed distributions. Fear not – there is still hope. You can scour through the list of community-submitted images that is hosted on VM Depot. The site provides a large list of images that can be used to create virtual machines on Azure without having to go through any effort. If you are not lucky enough to find the specific OS that you need in VM Depot, or if you have your own image that you’d rather use, for one of several business, compliance, or security requirements, then there is nothing stopping you from constructing your own image. In fact, the Azure website provides plenty of useful documentation that can help you prepare your image so that it is Azure-ready and so that it can run on Microsoft Azure IaaS infrastructure without any issues.

The first place to start is on the Information for Non-Endorsed Distributions page. While the page highlights the main points to be followed in building your own custom Linux image for use in building and deploying Azure VMs, there are some differences between different distributions and even between different versions of the same distributions.

In the article, I will provide an example of building a custom CentOS 5.9 image that has the basic server image along with the Azure prerequisites installed and configured. The image described in this article is currently available on VM Depot as the CentOS 5.9 image.

The images consists of a 30 GB VHD that contains around 2.2 GB worth of CentOS 5.9.

One final thing to note here is that the procedure and steps below are for building an on-premises VM on Hyper-V on Windows 8.1, Windows 2008 R2, or Windows 2012/2012 R2.

Unfortunately, in order to prepare an image for use in Azure, there are quite a few steps that need to be followed. In order to build the CentOS 5.9 image that I’ve published on VM Depot, I’ve followed the following steps, and I’ve tried to provide a screenshot for every important step so that hopefully this can be a useful guide:

1. Read the Azure documentation. Well, the first step is not really an actual step in the process, but it is nevertheless a recommended step. If you have some time, I would suggest reading the following documentation page first. You can find in it and in its linked pages all the information you need for building custom Linux images. The steps I list below are really taken from those documents are merely summarized here for convenience and to provide a specific example for the case of building a CentOS 5.9 image.
   • Starting point: http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-create-upload-vhd/
   • Take note of the following:
     • Install Linux Integration Services (LIS) v3.5 (or the latest available at the time). The page lists only v3.2.
     • Create a VHD, not a VHDX: “The newer VHDX format is not supported in Azure. You can convert the disk to VHD format using Hyper-V Manager or the convert-vhd cmdlet.”
     • All of the VHDs must have sizes that are multiples of 1 MB.
2. Build a new virtual machine in Hyper-V. I am going to skip the actual Hyper-V VM creation steps. But do make sure to do the following:
   • Create a VHD disk, not a VHDX.
   • Create a dynamically expanding disk of say 30 GB. This is the size of the image that will created in Azure Blob Storage once you upload the VHD at the end. Note the size is even – this is important otherwise you’ll get an error when uploading the image (see the “multiples of 1 MB” requirement above). Note that once all is installed, the actual image size will be around 2.2 GB.
   • I’d choose about 512 MB of RAM for the VM memory. There is no need to go crazy on RAM for the image preparation process.
   • I’d also pick only a single processor for the VM (the default).
   • Make sure you connect the VM to a NIC: either your host OS’ physical NIC or a virtual NIC will do. I typically use a virtual switch for each of my host’s NICs, and I use one or multiple based on my requirements. In this case, just connect a single NIC. You will need it for connecting to the Internet and downloading some packages onto the OS.
3. Get the ISO image for CentOS 5.9. This is an old image, so you need to get it from the vault:
   • Vault Location: http://vault.centos.org/
   • CentOS 5.9: http://vault.centos.org/5.9/isos/x86_64/CentOS-5.9-x86_64-bin-DVD-1of2.iso. Note that this is just a placeholder that will point you to the list of mirrors where you can download the ISO image.
4. Start your VM. First, attach the CentOS 5.9 ISO to the VM, then start the VM. On the CentOS home screen, enter linux text and press <ENTER> as shown in the second option on the screen.
   • 
5. Installer Wizard Options. Click OK to have the media tested. This should not take too long. The few screens that follow are self explanatory.
   • 
   • 
   • 
   • 
   • 
   • 
   • 
6. Partition Creation. Click Yes on the next screen to create a new partition. Choose the “create custom layout” option to create the new partition entering the partition information as shown below.
   • 
   • 
   • 
   • 
   • 
7. Ignore Swap Partition Warning. Accept the warning regarding not having a swap partition present. We don’t want to have it on the OS image.
   • 
8. Boot Loader Configuration. Next, choose the default option for the boot loader, and then pass any boot parameters. In our case, there are no parameters passed yet. We’ll do that at the end as per the Azure documentation. There is no need for a boot loader password in our case, and we’ve chosen to place the boot loader on the Master Boot Record.
   • 
   • 
   • 
   • 
   • 
9. Network Configuration. Next, you can configure the eth0 network interface as shown in the following screens. I’ve chosen to disable IPv6. Also, configure the network interface to use DHCP. If you do not have access to a DHCP server wherever you’re building the VM instance, you can choose a static IP and then change it back to use DHCP before uploading to Azure.
   • 
   • 
   • 
10. Host name. You’d want to specify the name of the host. You can use the generic name localhost.localdomain (or anything else if you like).
    • 
11. Time Zone and Root Password. On the next few screens, you’ll configure the time zone and specify the root password.
    • 
    • 
12. OS Packages Selection. As for the package installation, you don’t need to install any of the GUI packages. Depending on what you are prepping the image for, you can configure other packages. In my case, I’m only having it as a Server OS image which is a typical use case for Azure Linux VMs.
    • 
13. OS Installation. Complete the OS installation wizard by accepting the installation log location and initiating the OS installation process. At the end of the process, click Reboot to restart the VM with the new OS installed on it.
    • 
    • 
    • 
14. Additional Configuration. Upon rebooting, you’ll be presented with an option to make changes to some core components. In our case, we can skip this option as we’ve setup the network options before, and we do not need to make changes to the other services at this time.
    • 
    • 
15. Logon. Next, logon with the root account and enter the root password that was specified earlier in the setup wizard.
    • 
16. Remove the NetworkManager Package. As per the Azure documentation, you need to remove the NetworkManager package. Here is the easiest way to do that:
    • 
17. Edit the Network Configuration. Make sure the configuration options match the recommended options in the Azure documentation.
    • Edit the network file as follows (of course you don’t have to use vi – you can use whatever editor you like):
    • 
    • This is what the network file will look like:
    • 
    • And this is what we want it to end up looking like:
    • 
    • Next, edit the ifcfg-eth0 file for the first network interface (and only network interface in our case – if you have others, you can do the same for ifcfg-eth1, etc…):
    • 
    • This is what the file contents look like in my case (you are more likely to have a different MAC address specified in the file):
    • 
    • And this is how we want the file to look like:
    • 
    • Ensure the network service is started at boot time (see step 6 of the Azure documentation):
    • 
18. Download and Install Linux Integration Services v3.5 (or the latest available at the time you’re installing).
    • You can find the list of available LIS versions with the following URL: http://www.microsoft.com/en-us/search/Results.aspx?q=Linux%20Integration%20Services%20for%20Hyper-V&form=DLC
    • Once you download LIS, attach it to the Hyper-V VM, and then mount it onto the OS:
    • 
    • Then install LIS as follows:
    • 
    • Notice in the above case that the installation might fail due to existing conflicts. In that case, you’d need to remove the conflicting package.
    • 
    • And then re-attempt the LIS installation:
    • 
    • And then reboot:
    • 
19. Install Python 2.6. There are several ways to download and install Python 2.6.x. This is but one of them:
    • 
    • 
    • 
    • Verify that Python 2.6.x is installed:
    • 
    • If you like, set it in the path to make life easier:
    • 
    • Get the setuptools (needed for building the RPM for WALinuxAgent):
      • # wget --no-check-certificate https://bootstrap.pypa.io/ez_setup.py
      • # python ez_setup.py –insecure
    • 
20. Install pyasn1.
    • Download python_pyasn1:
    • 
    • 
    • 
    • Verify that the pyasn1 package is installed:
    • 
21. Get the Windows Azure Linux Agent (waagent). In the steps below, we are going to download the waagent from GitHub and build the package before installing it. You may choose to do this differently.
    • Install rpm-build:
    • 
    • 
    • Download waagent from GitHub:
    • 
    • Download the .spec file:
    • 
    • Extract the waagent archive:
    • 
    • Rename the extracted folder to match the version number of the latest version available on GitHub (in this case, it is 2.0.8). Then create an new archive off of the renamed folder, and copy the different files to the destination folders shown below:
    • 
    • Edit the walinuxagent.spec file.
    • 
    • Rename “initddir” to “initrddir” for CentOS:
    • 
    • Build the package based on the .spec file:
    • 
    • Make sure the package is written successfully as shown below:
    • 
    • 
    • Install waagent. Then verify the installation by inspecting waagent.log:
    • 
22. Make the final configuration changes specified in the Azure documentation.
    • Edit waagent.conf:
    • 
    • 
    • Edit yum.conf:
    • 
    • 
    • Edit fastestmirror.conf:
    • 
    • 
    • yum clean all:
    • 
    • Edit menu.lst:
    • 
    • 
23. Edit /usr/sbin/waagent. Update the python path in the script to point it to v2.6.x in order not to disrupt the environment version of Python (2.4.x) which is needed by different components. There are two locations that you’d need to update as shown below:
    • 
    • 
    • 
24. Deprovision the VM and make it ready for uploading to Azure Blob Storage.
    • 
25. Shutdown the VM.
26. Upload the VHD to your Azure Blob Storage account. For example, in my case, here is the PowerShell command I executed to upload my local CentOS59sys.vhd to the “public-vhds” container in my linuxvmdepot Azure Storage account:
    • Add-AzureVhd -Destination https://linuxvmdepot.blob.core.windows.net/public-vhds/CentOS59Sys.vhd -LocalFilePath 'D:\Hyper-V\Virtual Hard Disks\CentOS59sys.vhd'
    • The upload step might take a while depending on your Internet connection speed.
    • This is what it looks like in my storage case after it is finally uploaded:
    • 
27. Et viola, you’re done! You’re now ready to create an image off of the VHD and start creating Virtual Machines in Azure.

As you can notice, this process is pretty lengthy. While it only shows 25 main steps above, there are a ton of small embedded steps. While this can be automated, my goal in this article is to show the process with most of the details along with some accompanying screenshots that can help show what things would look like so you can compare to, as a baseline, while creating your own custom image. I wanted to give a specific example (CentOS 5.9) since it provides a fixed baseline that can be compared against as opposed to the more generic nature of the Azure documentation. Hopefully this helps.

The VHD image that I’ve created based on the steps listed above is available in VM Depot. Check it out at the following location (or by going to https://vmdepot.msopentech.com and search for CentOS 5.9):

https://vmdepot.msopentech.com/Vhd/Show?vhdId=50155&version=51283

If you run into issues or find that I’ve missed to include any specific steps, please contact me using the Contact link from this blog. Public comments on my blog are turned off since I do not have the time to audit and cleanup the constant bombardment of spam I keep getting all the time.

In a future post, I will be going over the possible issues you can run into when using a custom image like getting stuck during the provisioning step until the process times out after a couple of hours, and the ways to troubleshoot issues and what log files to look for after attaching the VHD to a healthy Linux VM.

[Edit – Jan 6th, 2015]: Added the WALinuxAgent package as an attachment in case someone wants to install a pre-built package without having to rpmbuild it from the sources.

[Edit – Feb 17th, 2015]: Added the step for getting setuptools just before step #20 (thanks to Guadalupe for discovering this).