Create ESXi image profiles for use by vSphere Auto Deploy, add custom third-party drivers to image profiles and export them, or perform upgrades.

With vSphere ESXi Image Builder you can create ESXi image profiles for use by vSphere Auto Deploy, add custom third-party drivers to existing image profiles and export to ISO or bundle, and perform upgrades. For basic concepts related to the way VMware vSphere software is created, packaged, and distributed, see Software Packaging Units That vSphere Lifecycle Manager Can Consume in the Managing Host and Cluster Lifecycle documentation.

Figure 1. Image Builder Architecture

Image Builder takes an image profile and one or more VIBs as input and produces an ISO or a ZIP as output.

You use vSphere ESXi Image Builder cmdlets for managing the software to deploy to your ESXi hosts in several different situations.

Table 1. Cases Where You Can Use vSphere ESXi Image Builder
Use Case for vSphere ESXi Image Builder Description
Create image profiles for use by vSphere Auto Deploy Use vSphere ESXi Image Builder to create an image profile that defines the VIBs that vSphere Auto Deploy uses to provision hosts.
Add custom third-party drivers to existing image profile and export to ISO or bundle When you add a third-party driver or extension custom VIBs to your ESXi hosts, use vSphere ESXi Image Builder to clone the base image provided by VMware, add the custom VIBs, and export to ISO or to offline bundle ZIP file.
Perform upgrades If you upgrade а system that includes custom extensions or drivers, you can use vSphere ESXi Image Builder to create a custom image profile that includes vSphere 8.0 compatible VIBs for the custom extensions. Export the custom image profile to an ISO or to a ZIP to upgrade your system by using vSphere Lifecycle Manager baselines.

The vSphere ESXi Image Builder cmdlets take image profiles and VIBs as input and produce various outputs.

Table 2. Input and Output to the vSphere ESXi Image Builder Cmdlets
Parameter Description
Input Image profiles and VIBs that are located in a software depot are used as input to PowerCLI cmdlets running on a Windows client.
Output PowerCLI cmdlets create custom image profiles that can be exported to an ISO image or an offline depot ZIP file. ISO images are used for installation. The ZIP depot can be used by vSphere Lifecycle Manager or by esxcli software commands to update or install images. Image profiles are also used in vSphere Auto Deploy rules to customize the software to provision ESXi hosts with.

Watch the video "Using Image Builder CLI" for information about vSphere ESXi Image Builder:

Image Profiles

Image profiles define the set of VIBs that an ESXi installation or update process uses. Image profiles apply to ESXi hosts provisioned with vSphere Auto Deploy. You define and manipulate image profiles with vSphere ESXi Image Builder.

Image Profile Requirements

You can create a custom image profile from scratch or clone an existing profile and add or remove VIBs. A profile must meet the following requirements to be valid.

  • Each image profile must have a unique name and vendor combination.
  • Each image profile has an acceptance level. When you add a VIB to an image profile with an vSphere ESXi Image Builder cmdlet, Image Builder checks that the VIB matches the acceptance level defined for the profile.
  • You cannot remove VIBs that are required by other VIBs.
  • You cannot include two versions of the same VIB in an image profile. When you add a new version of a VIB, the new version replaces the existing version of the VIB.

Image Profile Validation

An image profile and its VIBs must meet several criteria to be valid.

  • Image profiles must contain at least one base VIB and one bootable kernel module.
  • If any VIB in the image profile depends on another VIB, that other VIB must also be included in the image profile. VIB creators store that information in the SoftwarePackage object's Depends property.
  • VIBs must not conflict with each other. VIB creators store conflict information in the SoftwarePackage object's Conflicts property.
  • Two VIBs with the same name, but two different versions, cannot coexist. When you add a new version of a VIB, the new version replaces the existing version of the VIB.
  • No acceptance level validation issues exist.

When you make a change to an image profile, vSphere ESXi Image Builder checks that the change does not invalidate the profile.

Dependency Validation
When you add or remove a VIB, vSphere ESXi Image Builder checks that package dependencies are met. Each SoftwarePackage object includes a Depends property that specifies a list of other VIBs that VIB depends on. See Structure of ImageProfile, SoftwarePackage, and ImageProfileDiff Objects
Acceptance Level Validation
vSphere ESXi Image Builder performs acceptance level validation each time an image profile is created or changed. vSphere ESXi Image Builder checks the acceptance level of VIBs in the image profile against the minimum allowed acceptance level of the profile. The acceptance level of the VIB is also validated each time the signature of a VIB is validated.

VIB Validation During Export

When you export an image profile to an ISO, vSphere ESXi Image Builder validates each VIB by performing the following actions.

  • Checks that no conflicts exist by checking the Conflicts property of each SoftwarePackage object.
  • Performs VIB signature validation. Signature validation prevents unauthorized modification of VIB packages. The signature is a cryptographic checksum that guarantees that a VIB was produced by its author. Signature validation also happens during installation of VIBs on an ESXi host and when the vSphere Auto Deploy server uses VIBs.
  • Checks that VIBs follow file path usage rules. VMware tests VMwareCertified and VMwareAccepted VIBs to guarantee those VIBs always follow file path usage rules.

Working with Acceptance Levels

Hosts, image profiles, and individual VIBs have acceptance levels. VIB acceptance levels show how the VIB was tested. 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.

Host acceptance levels
The host acceptance level determines which VIBs you can install on a host. You can change a host's acceptance level with ESXCLI commands. By default, ESXi hosts have an acceptance level of PartnerSupported to allow for easy updates with PartnerSupported VIBs.
Note: VMware supports hosts at the PartnerSupported acceptance level. For problems with individual VIBs with PartnerSupported acceptance level, contact your partner's support organization.
Image profile acceptance levels
The image profile acceptance level is set to the lowest VIB acceptance level in the image profile. If you want to add a VIB with a low acceptance level to an image profile, you can change the image profile acceptance level with the Set-EsxImageProfile cmdlet. See Set the Image Profile Acceptance Level.

The vSphere Lifecycle Manager does not display the actual acceptance level. Use vSphere ESXi Image Builder cmdlets to retrieve the acceptance level information for VIBs and image profiles.

VIB acceptance levels
A VIB's acceptance level is set when the VIB is created. Only the VIB creator can set the acceptance level.

If you attempt to provision a host with an image profile or VIB that has a lower acceptance level than the host, an error occurs. Change the acceptance level of the host to install the image profile or VIB. See Change the Host Acceptance Level. Changing the acceptance level of the host changes the support level for that host.

The acceptance level of a host, image profile, or VIB lets you determine who tested the VIB and who supports the VIB. VMware supports the following acceptance levels .

VMwareCertified
The VMwareCertified acceptance level has the most stringent requirements. VIBs with this level go through thorough testing fully equivalent to VMware in-house Quality Assurance testing for the same technology. Today, only I/O Vendor Program (IOVP) program drivers are published at this level. VMware takes support calls for VIBs with this acceptance level.
VMwareAccepted
VIBs with this acceptance level go through verification testing, but the tests do not fully test every function of the software. The partner runs the tests and VMware verifies the result. Today, CIM providers and PSA plug-ins are among the VIBs published at this level. VMware directs customers with support calls for VIBs with this acceptance level to contact the partner's support organization.
PartnerSupported
VIBs with the PartnerSupported acceptance level are published by a partner that VMware trusts. The partner performs all testing. VMware does not verify the results. This level is used for a new or nonmainstream technology that partners want to enable for VMware systems. Today, driver VIB technologies such as Infiniband, ATAoE, and SSD are at this level with nonstandard hardware drivers. VMware directs customers with support calls for VIBs with this acceptance level to contact the partner's support organization.
CommunitySupported
The CommunitySupported acceptance level is for VIBs created by individuals or companies outside of VMware partner programs. VIBs at this level have not gone through any VMware-approved testing program and are not supported by VMware Technical Support or by a VMware partner.

Change the Host Acceptance Level

You can lower the host acceptance level to match the acceptance level for a VIB or image profile you want to install.

The acceptance level of each VIB on a host must be at least as high as the acceptance level of the host. 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. For more information on acceptance levels, see Working with Acceptance Levels.

Warning: Changing the host acceptance level to CommunitySupported affects the supportability of your host and might affect the security of your host.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. Retrieve the acceptance level for the VIB or image profile.
    Option Description
    View information for all VIBs 
    esxcli --server=server_name software
					 sources vib list --depot=depot_URL
    View information for a specified VIB 
    esxcli --server=server_name software
					 sources vib list --viburl=vib_URL
    View information for all image profiles 
    esxcli --server=server_name software
					 sources profile list --depot=depot_URL
    View information for a specified image profile 
    esxcli --server=server_name software
					 sources profile get --depot=depot_URL
					 --profile=profile_name
  2. View the host acceptance level. 
    esxcli --server=server_name software acceptance get
  3. Change the acceptance level of the host. 
    esxcli
				--server=server_name software acceptance set --level=acceptance_level

    The value for acceptance_level can be VMwareCertified, VMwareAccepted, PartnerSupported, or CommunitySupported. The values for acceptance_level are case-sensitive.

    Note: If the host has a higher acceptance level than the VIB or image profile you want to add, you can run commands in the esxcli software vib or esxcli software profile namespace with the --force option. When you use the --force option, a warning appears because you enforce a VIB or image profile with lower acceptance level than the acceptance level of the host and your setup is no longer consistent. The warning is repeated when you install VIBs, remove VIBs, or perform certain other operations on the host that has inconsistent acceptance levels.

Set the Image Profile Acceptance Level

If you want to add a VIB to an image profile, and the acceptance level of the VIB is lower than that of the image profile, you can clone the image profile with a lower acceptance level or change the image profile's acceptance level.

You can specify VMwareCertified, VMwareAccepted, PartnerSupported, or CommunitySupported as an acceptance level of an image profile. If you lower the acceptance level, the level of support for the image profile and hosts that you provision with it changes. For more information, see Working with Acceptance Levels.

Prerequisites

Install PowerCLI and all prerequisite software. See Configure vSphere ESXi Image Builder.

Procedure

  1. In a PowerCLI session, run the Add-EsxSoftwareDepot cmdlet for each depot you want to work with.
    Option Action
    Remote depot Run Add-EsxSoftwareDepot -DepotUrl <depot_url>.
    ZIP file
    1. Download the ZIP file to a local file system.
    2. Run Add-EsxSoftwareDepot -DepotUrl C:\<file_path>\<offline-bundle>.zip
    The cmdlet returns one or more SoftwareDepot objects.
  2. Get the acceptance level for the image profile. 
    Get-EsxImageProfile -Name string
  3. Set the acceptance level of the image profile. 
    Set-EsxImageProfile -Name string -AcceptanceLevel level