Wednesday 6 April 2016

Custom ESXi Image - ISO using PowerCLI

There comes a time when you have purchased a new hardware to run your ESXi software and discover that the installable base media provided by VMware does not include the drivers or the drivers are out of date. In the world of Windows (Plug and Play) it would discover the hardware and prompt you to provide the drivers so that Windows would install/update the drivers for the hardware. For ESXi if the drivers are not present during load time then the hardware will possibly not work.

VMware uses VIB (vSphere Installation Bundle) as a way for vendors to distribute their drivers. To install these VIBs you can either use Update Manager or command line (esxcli). Now this is all good but it does mean you have to first install the base ESXi then use one of the steps above to install/update the drivers.  

Some people might feel that it is OK to update the drivers using the above methods but what if it was the network card that was the new hardware and you needed new drivers. Without the network card you wouldn't be able to use Update Manager as the host doesn't have network connectivity to vCenter. With command line you could possible mount an ISO via ILO with your drivers or use a USB stick to install but again lots of extra steps. Extra steps usually means more space for error i.e. missing a crucial step needed. 

What if you wanted to slipstream the drivers into the base installable media so that once you have installed ESXi you have all the hardware ready for you to use and not need to install additional drivers, just like Windows ?

You can do this by creating a custom ESXi build where you would add/remove the drivers that you would like in your ESXi install media. Some of the big hardware vendors such as HP and DELL already have custom ESXi builds which includes all the drivers of the hardware that they sell to run ESXi. This is so that you would not need use one of the mentioned methods above to add the drivers which means less steps for you to get your hardware working. Using these vendor images are great as it saves time, repeatable and ensures that you are using verified, tested drivers from the vendor. It also ensures that each of your build is consistent with the driver version as you roll them out.

VMware provides a method (vSphere ESXi Image Builder) to help you create your own custom ISO. You will need to use VMware PowerCLI to access this method which I will show you in this post. Using this method you are able to update existing drivers or add drivers or even remove drivers. 

My example is based on using HP's custom image as I am installing ESXi to a HP server so all the HP management and drivers VIBS are already included in this image. Where I am currently working we use Xsigo (oracle fabric interconnect) and the drivers for these are not included in the base image of ESXi so we will need to add these drivers.

There are some pre-requisites software that are needed before we start creating our custom VMware ESXi iso:
  • VMware PowerCLI (I used 6.0.0 R3) install on a server or workstation that you will be using to create our image
  • Offline binary files of vSphere ESXi 6, please note download the "zip" and not "iso" one
  • Download the driver bundle that you wish to add to your base ESXi image, for me this would be the Xsigo drivers bundle

Steps to create and add drivers to a custom ESXi image

1. Create a new directory and copy your offline bundle version of ESXi 6 and driver bundle that you wish to add to your custom ISO image. In my example I have created a directory under c:\esxi

The following steps may be applicable to you depending on the security settings you have on your machine:
  • Right select one of the "zip" files and select "properties" within the directory where all your bundle software are in the step 1
  • Check if "unblock" is selectable. If it is then select it to unblock the file. By doing this you will not need to run PowerCLI in administrator mode which makes life a bit more simpler
2. Install PowerCLI on your workstation or server if you have not done so and launch it
Optional Step - Check your version of PowerCLI is the same version as I am using in this article, run Get-PowerCLIVersion
3. We need to mount the ESXi image within our PowerCLI session so that we can select it to be used. The command to run would be Add-EsxSoftwareDepot -DepotUrl PathToYourZipFile . Make sure you select your ESXi zip file and not your driver zip file. So for my example it would be: Add-EsxSoftwareDepot -DepotUrl c:\esxi\VMware-ESXi-6.0.0-Update1-3380124-HPE-600.9.4.5.11-Jan2016-depot.zip . You should see under Depot Url the path to your zip file that you have just added.

4. Run Get-EsxImageProfile which will list the images that we can use
5. By default the image is read only and you would need to clone the image first and work on the cloned image. To do that you would need the name of the image. As you can see from the above screenshot the name is not fully displayed. So we will run the following command Get-EsxImageProfile | Select Name to just return the name of the image for us to use in the next step
6. With the above information we will now clone the image to a new one. At this step we would need to decide on the name we wish to name our image. Also we need to think of a name to fill in for our "vendor" section in the command line which is mandatory. It is up to you what you would like "vendor" to be. The command would be New-EsxImageProfile -CloneProfile ProfileNameYouWouldLikeToClone -Name NewNameForYourCustomImage -Vendor YourChoice.

For my example I decided that the new name should be the same as my image name but added "Xsigo" to the end and for the vendor I just called it "MyIT". The command I used is New-EsxImageProfile -CloneProfile HPE-ESXi-6.0.0-Update1-600.9.4.5.11 -Name HPE-ESXi-6.0.0-Update1-600.9.4.5.11-Xsigo -Vendor MyIT. Please Note this command is case-sensitive so make sure you follow the case otherwise you will get errors
7. Now run Get-EsxImageProfile | Select Name,Vendor and we should see our original image and our newly clone image to work on. You will see the Vendor name is the one you created
8. We now need to mount our drivers within the PowerCLI session so that we can add our drivers to our custom image we have created at step 6. Run Add-EsxSoftwareDepot -DepotUrl PathToYourZipFile. Make sure you select the driver zip file my example it would be Add-EsxSoftwareDepot -DepotUrl C:\esxi\xsigo_6.0.0.ESX-1vmw.600.0.0.2494585.zip. You should see under Depot Url the path to your zip file that you have just added.
9. To add the drivers to your custom ESXi iso you will need to know how many "software packages" are within your driver zip file. There are a few ways you can query your driver package like by name, version, vendor etc. I used the -SoftwareDepot which homes in to the actual path of the zip file and only return information specifically for that package. So the command would be: Get-EsxSoftwarePackage -SoftwareDepot C:\esxi\xsigo_6.0.0.ESX-1vmw.600.0.0.2494585.zip. This returned that I have 11 software packages that I would need to add to my custom image.
10. Now we have the name of the software packages (first column on above screenshot) we can use the command Add-EsxSoftwarePackage -SoftwarePackage SoftwarePackageName -ImageProfile OurCustomImageName to add the drivers. A warning here, it is possible that certain drivers need to be added first before you can do the next one as shown in the screenshot below:
As you can see I tried to add driver "net-ib-mad" but it throws an error saying it requires another component to be part of the image. Then it goes on to tell you that within your depot you already have that driver which gives you an indication to install that one first, "net-ib-core". So there could be a few trial and errors to start off with to get the right order of drivers to install.

So to give an example of the command I used Add-EsxSoftwarePackage -SoftwarePackage net-mlx4-core -ImageProfile HPE-ESXi-6.0.0-Update1-600.9.4.5.11-Xsigo
Repeat the steps until you have added all the drivers to your custom image.

11. To check if you have added all the drivers to your custom image you could do the following command $ip = Get-EsxImageProfile -Name OurCustomImageName where $ip is storing the properties of your custom image details. The command I used for the example is $ip = Get-EsxImageProfile -name HPE-ESXi-6.0.0-Update1-600.9.4.5.11-Xsigo
If we run $ip.viblist it will list all the software packages that are within our custom iso. You can go through the list manually to see if all your drivers are there or write a more custom queries to drill down to a smaller list.
  
So for me I can see from step 9 that the Creation Date for all my drivers in that particular bundle are exactly the same so I decided to use this field to help me filter down. I used the command $ip.viblist | Where-Object {$_.CreationDate -gt "04/29/2015" -and $_.CreationDate -lt "05/01/2015"}
You could run other command such as $ip.viblist | Where-Object {$_.vendor -like "intel*"} which would return packages from vendor like intel.

12. Now that we know we have our drivers in our image we need to export it to a iso format so that we can use it to install our ESXi. The command to be used is Export-EsxImageProfile -ImageProfile OurCustomImageName -FilePath FilePathAndNameOfOurISO -ExportToIso. Remember to add ".iso" to the end of your file name for your custom ISO. The command I used is  Export-EsxImageProfile -ImageProfile HPE-ESXi-6.0.0-Update1-600.9.4.5.11-Xsigo -FilePath C:\esxi\HPE-ESXi-6.0.0-Update1-600.9.4.5.11-Xsigo.iso -ExportToIso
Once the job is done you should see your iso file in the location that you have specified

Steps to remove drivers to a custom ESXi image

You normally shouldn't need to do this as when you add drivers it should automatically update the existing drivers to the new version but there could be times when it doesn't do it and you need to remove the drives first. Again using the above example

1. At step 6 once you have created your custom image and know which drivers you would like to remove use the following command Remove-EsxSoftwarePackage -SoftwarePackage SoftwarePackageName -ImageProfile OurCustomImageName. I used
Remove-EsxSoftwarePackage -SoftwarePackage nmlx4-en -ImageProfile HPE-ESXi-6.0.0-Update1-600.9.4.5.11-Xsigo
Repeat the step until you have removed all the drivers required
2. Use step 11 to help you verfiy that the drivers is no longer in the image
3. Use step 12 to then create a new iso which does not contain the drivers in your new image

As you can see it is quite easy to add/remove/update drivers in a custom ESXi image that you wish to create. You can create a custom iso which includes all the drivers for the different host that you may have in your environment. This would save time as you won't need to write documentation for each type of server hardware build. You would have one image and it will have all the drivers needed for your estate.

Enjoy

References

You may need to log in to My VMware to download the following software :

3 comments:

  1. This is an excellent helpful and well written article and i appreciate the effort you have put into creating this. This will help me very much for next set of builds. Thank you!!!!

    ReplyDelete
  2. Thank you very much. Worked like a charm :)

    ReplyDelete

New Azure KMS IP and domain Addresses for activation

For Windows virtual machines deployed into Azure using marketplace images you may have created rules in your NSG or firewalls to allow the s...