Use the vSphere Automation APIs to run general operations on the ESXi hosts in your vSphere environment.
You can retrieve information about the hosts, create a standalone host, disconnect, and reconnect an ESXi host to a vCenter Server system.
How Do I Retrieve Information About ESXi Hosts
You retrieve information about the ESXi hosts running in a vCenter Server instance by listing only the ESXi hosts that you are interested in.
- The name or unique identifier of the host.
- Clusters, data centers, or folders that contain the host.
- Connection state of the host which can be one of the following: CONNECTED, DISCONNECTED, or NOT_RESPONDING.
- Power state of the host which can be one of the following: POWERED_OFF, POWERED_ON, or STANDBY.
The function returns a list of com.vmware.vcenter.HostTypes.Summary objects that contain information about up to 2500 hosts that match all specified criteria. You can use the list to retrieve information about the returned ESXi hosts.
How Do I Add a Standalone ESXi Host to vCenter Server
You can use the vSphere AutomationAPIs to add a standalone host to a vCenter Server instance.
Add a single ESXi host to a vCenter Server instance by calling the create function and passing a com.vmware.vcenter.HostTypes.CreateSpec instance as parameter. When you create the host specification, make sure that you set the IP address or the DNS resolvable host name and the administrator credentials.
How Do I Disconnect and Reconnect ESXi Hosts
You can use the vSphere Automation APIs to connect ESXi hosts to a vCenter Server instance and make the hosts managed. You can temporarily disconnect a managed host from a vCenter Server instance and reconnect the host, for example, to refresh the ESX agents on the host.
When you add a host to a vCenter Server instance, the host is connected to vCenter Server and becomes a managed host. To disconnect a managed host from a vCenter Server instance, call the disconnect function and pass the host identifier as a parameter. The managed host and its associated virtual machines remain in the inventory but vCenter Server temporarily stops managing and monitoring them.
To reconnect a managed host to a vCenter Server instance, call the connect function and pass the host identifier as a parameter. As a result, the connection status of the host changes, and vCenter Server resumes managing the host and its associated virtual machines.
If you want to delete a host and all its associated virtual machines from the inventory, you can remove the host from the vCenter Server instance. To delete a disconnected host from a vCenter Server instance, call the delete function and pass the host identifier as a parameter.
How Do I Configure ESXi Entropy
You can use the vSphere Automation API to feed external entropy data to an ESXi host in your inventory. You can also query the current entropy levels on the host and add external entropy data when needed.
Entropy is a measure of the randomness or diversity of a data-generating function. In releases prior to vSphere 8.0 Update 1, ESXi supported only CPU-based entropy data generated from interrupts or manufacturer provided interfaces, such as RDSEED and RDRAND. High-quality entropy is important for the proper functioning of security-related operations such as generating encryption keys for secure communication over the network. Starting with vSphere 8.0 Update 1, you can add external entropy sources to an ESXi host and in this way ensure the high quality of the entropy data on that host. You provide external entropy data by using devices such as hardware security modules (HSMs) which are FIPS 140-3 and EAL4 certified.
You can configure the ESXi entropy sources by using the VMkernel boot options. To use external entropy sources, set the entropySources value to more than or equal to 8. For more information about how to set the desired entropy sources by using the VMkernel boot options, see Controlling ESXi Entropy in the vSphere Security documentation.
You can also configure external entropy sources in the kickstart file for the ESXi scripted installation. See Configuring External Entropy Sources During Scripted Installation.
If a host is configured to use only external entropy sources, that is, entropySources is set to 8, you must keep supplying the external entropy data through the vSphere Automation API. In case the entropy in the host gets exhausted, the host becomes unresponsive and might require a hard reboot or re-installation to recover the host from this situation.
Querying Entropy Data on a Host
To retrieve details about the external entropy available on an ESXi host, use the ExternalPool service. You must have the Host.Entropy.Read privilege.
You can check whether an external entropy source is added to a host by calling the get(host_id) method of the com.vmware.vcenter.host.entropy.ExternalPool interface and passing the host ID as parameter. The method returns an ExternalPool.Info instance that contains detailed information about the external entropy data on the host.
| External Entropy Data Detail | Description |
|---|---|
| getStatus() | Indicates whether an external entropy source is added for a host. |
| getCapacity() | Shows the maximum capacity of external entropy data in bytes that a host can store in the VMkernel entropy pool. When you feed the host with additional external entropy data, make sure that you do not exceed this maximum capacity. Otherwise, all extra entropy data is discarded. |
| getCurrentlyAvailable() | Indicates the current amount of entropy data in bytes available in the VMkernel entropy pool on the host. |
| getInactiveSourceTimeout() | Indicates the amount of time in seconds that can elapse without any activity between the host and the external entropy source. Your application must check periodically the levels of entropy data on the host and send entropy data from the external source when required. When this timeout exceeds an esx.audit.entropy.external.source.disconnected VMkernel Observation (VOB) is logged. This system event suggests possible loss of connection to the external entropy source. For the full list of available entropy VOBs in vSphere 8.0, see the VMware knowledge base article at https://kb.vmware.com/s/article/89074. |
| getLowWatermark() | Indicates the threshold in bits sufficient for the in-memory cache to operate successfully. When the in-memory entropy cache is running low and the threshold is reached, an esx.audit.entropy.available.low VOB is logged. For more information about the entropy VOBs, see the VMware knowledge base article at https://kb.vmware.com/s/article/89074. |
Adding External Entropy Data to a Host
To add entropy data from an external entropy source to a host, you must have the Host.Entropy.Write privilege. Use the ExternalPool service and call the add(host_id, add_spec) method. Pass the host ID and an ExternalPool.AddSpec instance as method parameters. The ExternalPool.AddSpec instance contains the Base64 encoded external entropy data. You must convert the binary data coming from the external entropy source to Base64 format so that the host can consume it. As a result, the method returns an instance of the ExternalPool.AddResult class.
When the external entropy data reaches the host, the entropy daemon stores it first in the in-memory cache and the storage cache. Then the external entropy data is pushed to the VMkernel entropy pool from which it is fed to the applications in need.
The entropy data in the storage cache persists on the host disk and is only consumed during the ESXi booting. The default storage file size is 4MiB and can be configured through the ESXCLI commands. See the ESXCLI Command Reference documentation.
