Yet again, customer questions make the best blog posts. This time, it’s about retrieving the firmware and drivers from an ESXi host.
So far, the customer uses esxcli which required either PowerCLI or direct SSH access, both were not the preferred choices in this case.
High-level overview
Starting with vSphere 7, vSphere Lifecycle Manager (vLCM) can handle this task. This blog post will show you how to create a HCL report for a given host which contains all the required information about firmware and drivers, as well as the bonus information about the support status of the system and devices.
In the vSphere UI these results are available in the “Hardware Compatibility” overview within the “Update” tab:
Since vLCM is a new feature, REST endpoints are available for these tasks:
- Update HCL data for vCenter
- Query information about the available vSphere releases
- Create a HCL report for a given host
- Query/Download the resulting output (report)
The API documentation for all tasks in this post is available here:
https://developer.vmware.com/apis/vsphere-automation/latest/esx/hcl/
Execution example
For this example I am working with these values:
- My API endpoint (vCenter) with the name cube-vcsa-01.lab.why-did-it.fail
- An ESXi host named cube-esx-01.lab.why-did-it.fail with the MoRef id “host-11”
Sync HCL data
Assuming is this is the first time you are using vLCM and making a HCL query, you need to update the HCL data in vCenter.
I am using curl to trigger the update:
curl -X POST 'https://cube-vcsa-01.lab.why-did-it.fail/api/esx/hcl/compatibility-data?action=download&vmw-task=true' -H 'vmware-api-session-id: XXX' -H 'Content-type: application/json'
If you want to check the last sync beforehand, you can query the last update time by using a GET method.
curl -X GET 'https://cube-vcsa-01.lab.why-did-it.fail/api/esx/hcl/compatibility-data/status' -H 'vmware-api-session-id: XXX'
The response provides a timestamp:
{
"updated_at": "2022-10-12T03:48:46.318Z",
"notifications": {}
}
Query release data
Each HCL check that you create will be validated for a given vSphere release. In order to get a list of supported vSphere releases you can query the HCL database for the available release information for a given host.
curl -X GET 'https://cube-vcsa-01.lab.why-did-it.fail/api/esx/hcl/hosts/host-11/compatibility-releases' -H 'vmware-api-session-id: XXX'
On success, you will see a similar Response body:
{
"current_compatibility_release": "ESXi 7.0 U3",
"newer_compatibility_releases": [
"ESXi 8.0"
],
"notifications": {
"warnings": []
}
}
Take note of the release that you want to use as a baseline. I will use "ESXi 7.0 U3".
On a side note: If your host is unsupported, vLCM will tell you so :-)
{
"error_type": "UNSUPPORTED",
"messages": [
{
"args": [],
"default_message": "Hardware compatibility checks are currently not supported for the selected vendor model.",
"localized": "Hardware compatibility checks are currently not supported for the selected vendor model.",
"id": "com.vmware.vcIntegrity.hcl.host.vendor.unsupported.summary"
}
]
}
Create a report for an ESXi host
You can now create a task that prepares a report using the information about the baseline release and the target host as parameters.
curl -X POST 'https://cube-vcsa-01.lab.why-did-it.fail/api/esx/hcl/hosts/host-11/compatibility-report?vmw-task=true' -H 'vmware-api-session-id: XXX' -H 'Content-type: application/json' -d '{ "release": "7.0 U3" }'
You can use identifier to retrieve the hardware compatibility report, but I prefer to query the same resource for the results which I will describe next.
Retrieve the report (easy way)
Using a GET method against the same resource returns the last generated hardware compatibility report.
curl -X GET 'https://cube-vcsa-01.lab.why-did-it.fail/api/esx/hcl/hosts/host-11/compatibility-report' -H 'vmware-api-session-id: XXX'
The response is a JSON body containing the EsxHclHostsCompatibilityReportResult.
Here is an excerpt of the results:
{
"identifier": "52e90aa8-5fea-c410-a7a5-282ca7b01da1",
"report": {
"devices_hcl": [
{
"vcg_link": "https://www.vmware.com/resources/compatibility/detail.php?deviceCategory=io&productid=34628",
"compatibility": "COMPATIBLE",
"device": {
"used_by_vsan": false,
"vid": "8086",
"driver": {
"name": "ixgben",
"version": "1.10.3.0-1OEM"
},
"model_name": "82599 10 Gigabit Dual Port Network Connection",
"pci_address": "0000:03:00.0",
"vendor": "Intel(R)",
"svid": "103c",
"firmware": {
"version": "0x80000838, 1.2836.0"
},
"ssid": "17d0",
"sub_class_code": "00",
"class_code": "02",
"did": "10fb"
},
"supported_releases": [
"ESXi 7.0 U3"
]
},
{
"vcg_link": "https://www.vmware.com/resources/compatibility/detail.php?deviceCategory=io&productid=35530",
"compatibility": "COMPATIBLE",
"device": {
"used_by_vsan": false,
"vid": "10df",
"driver": {
"name": "lpfc",
"version": "14.0.169.26-5vmw"
},
"model_name": "Emulex LightPulse LPe16000 PCIe Fibre Channel Adapter",
"pci_address": "0000:84:00.0",
"vendor": "Emulex Corporation",
"svid": "103c",
"ssid": "197e",
"sub_class_code": "04",
"class_code": "0c",
"did": "e200"
},
"supported_releases": [
"ESXi 7.0 U3"
]
},
],
"target_release": "ESXi 7.0 U3",
}
The second method to retrieve the report is using the report ID that was returned as response to the “create report”-task. Using this ID, you can query the reports API (/api/esx/hcl/reports/) to get a download location for the report.
Summary
With these simply steps you can now automate your HCL checks to feed your report tools or prepare a bulk check of your environment. So far, this was tedious work that took a look of effort in bigger environments. Also, I recommend to take a look into the response body, it is quite verbose and might offer you some more insights about your environment.
Comments