How to: Build a custom image with vSphere ESXi Image Builder CLI

In February I’ve build myself a new home lab with some Shuttle DS81’s, as I described in detail. But due to the vSphere 6 release date and the upcoming ‘Barista-as-a-Service’-VMUG demo I used vSphere 5.5 Update 2. But now vSphere 6 is GA and the VMUG demo was a success, so it’s time for an upgrade. In February I did a clean install using the custom ESXi image I had burned to DVD. But now I wanted to try a enterprise-like install without any downtime using VMware Update Manager.

Back then I customised the ESXi 5.5 ISO with the VMware Front Experience ESXi-Customizer to include the drivers for the Realtek 8111G network interface. So, I imagined it would be a piece of cake because I already had the right driver and the experience of the previous install. WRONG!

Importing the ESXi 6 custom image in VMware Update Manager resulted in the following error, ‘The uploaded upgrade package is corrupted’.

After some investigation I found that this was due to the VMware Front Experience ESXi-Customizer. Something the already acknowledged but what can I say, I don’t like to read the manual ;-). From their site:

“ESXi 5.x install ISOs that were customized with ESXi-Customizer can not be imported into VMware vCenter Update Manager. There is no resolution for this issue.”

 

So, we need to build a custom image to use with vSphere Update Manager and I quickly found an alternative with the vSphere ESXi Image Builder CLI. This time I did read the manual:

A quick note about working with individual VIBs vs. Software Depots. You can download individual VIBs, and you can use the vSphere Update Manager or ESXCLI command to install them on your ESXi hosts. However, there is no way to import a standalone VIB into an Image Builder CLI session without first packaging the VIB into a Software Depot. So remember, when working with the Image Builder CLI you need to download the software depot (.zip) and not the individual VIBs (.vib).

There are six basic steps to creating a custom ESXi installation image:

Step 1: Download the software depots.

Start by downloading the VMware software depot from http://www.vmware.com/downloads and the driver you want to add to the ISO-image. In this case the driver for the Realtek 8186 in the Shuttle DS81 (provided by v-Front.de).

Step 2: Import the software depots

Next, start your PowerCLI session and import the software depots using the “Add-EsxSoftwareDepot” cmdlet. Import the VMware offline bundle you have downloaded.

To list the available image profiles, use the “Get-EsxImageProfile” cmdlet.

Step 3: Create an Image Profile

After the software depots have been imported the next step is to create an image profile using the “New-EsxImageProfile” cmdlet. There are two ways to create a new image profile, you can create an empty image profile and manually specify the VIBs you want to add, or you can clone an existing image profile and use that as your starting point. I cloned an existing image profile and named it “DS81-net51” identifying the host type and added driver.

Step 4: Change the Acceptance level

Hosts, image profiles, and individual VIBs have acceptance levels. VIB acceptance levels show tested the VIB. Understanding what each acceptance level implies, how to change levels, and what a change implies is an important part of installation and update procedures. Acceptance levels are set for hosts, image profiles, and individual VIBs. The default acceptance level for an ESXi image or image profile is PartnerSupported.

To match the acceptance level for a VIB or image profile you want to install to the host, you can lower acceptance level. The acceptance level of each VIB on a host must be at least as high as the host acceptance level. For example, you cannot install a VIB with PartnerSupported acceptance level on a host with VMwareAccepted acceptance level. You must first lower the acceptance level of the host.

To list the available image profiles and check the acceptance level, use the “Get-EsxImageProfile” cmdlet.

Next, start your PowerCLI session and import the software depots using the “Add-EsxSoftwarePackage” cmdlet. Import the VMware offline bundle you have downloaded.

Step 5: Add/Remove VIBs

Next, you use the “Add-EsxSoftwarePackage” and “Remove-EsxSoftwarePackage” cmdlets to add and remove VIBs to/from your image profile. In the example below I first added the net51-driver offline bundle to the depot.

To check the addition, you can list all the VIBs in the depot. I added a filter to only display the driver provided by VFrontDe.

No to inject the additional drivers into to the custom profile I created by cloning the “VMware ESXi-6.0.0-2494585” image profile  use the “Add-EsxSoftwarePackage” cmdlet.

Step 6: Save the Image Profile

After adding the VIBs you need the next step is to export the image profile. You can export the Image Profile as a software depot (.zip) or as an ISO file (.iso).

You now have a custom ISO image which you can use to upgrade the Shuttle DS81 using vSphere Update Manager. When new hosts are installed using the custom image profile all the VIBs you added will be installed on the host as part of the install.

So, just import the new custom ESXi 6 ISO image in VMware Update Manager and you’re good to go.