When you commit a draft software specification, you make the committed draft the desired state for that cluster or standalone host. If all hosts in the cluster are compliant with the desired state, you can remediate the cluster. If the single standalone host is compliant with the desired state, you can update the ESXi host to that state.

You can use the methods provided with the com.vmware.esx.settings.clusters.Software or com.vmware.esx.settings.hosts.Software interface to manage a desired state for a cluster or a standalone host. Before you apply a desired state on a cluster or a standalone host, you can run pre-checks to ensure that all hosts in the cluster or the single host are in a good state to be remediated. The pre-checks verify whether any of the hosts in the cluster or the single standalone host must be rebooted or are in maintenance mode. You can also check the compliance of the cluster or the standalone host against the desired state. See Checking the Compliance Against the Desired State.

You can export a software specification created for a cluster or a standalone host by using one of the following formats:
  • An offline bundle in a ZIP file format.
  • An ISO image.
  • A JSON file.

Use the vSphere Lifecycle Manager API to import a software specification as a draft and then edit it. You have several options for running the import operation depending on the location and format of the desired software state.

Exporting and Importing a Desired State

Use the vSphere Automation API to export the desired software state of a cluster or a standalone host. Then you can import the desired state to a different cluster or host in the same or a different vCenter Server instance.

Exporting a Desired State

To export a desired state, you can use one of the following methods:
  • For a cluster, call the export(cluster_ID, export_spec) method of the com.vmware.esx.settings.clusters.Software interface.
  • For a standalone host, call the export(host_ID, export_spec) method of the com.vmware.esx.settings.hosts.Software interface.
This method does not export any information about the solutions available on the cluster or the standalone host since the constraints set by these solutions might not be applicable for another cluster or host. Pass as parameters the cluster or the standalone host ID, and an instance of the respective SoftwareTypes.ExportSpec class.
You can choose how to export the desired software specification.
  • Export as an ISO image. Call the setExportIsoImage(exportIsoImage) method of the ExportSpec instance and pass true as an argument. Use the exported ISO image for performing clean installs and for bootstrapping purposes. You can upload the ISO file into the Jetty Web server on the target vCenter Server instance but you cannot use ISO files to manage the life cycle of clusters or a standalone host through the vSphere Lifecycle Manager feature.
  • Export as an offline bundle in a ZIP file format. Call the getExportOfflineBundle() method of the ExportSpec instance. You can use the exported offline bundle to create a depot and add its components to the resources managed by the Depot Manager module.
  • Export as a JSON file holding the desired state specification. Call the setExportSoftwareSpec(exportSoftwareSpec) method of the ExportSpec instance and pass true as argument. You can then reuse the JSON file to apply the desired state that it contains to another cluster or standalone host in the same or in a different vCenter Server instance. Note that the JSON file holds only the description of the desired state. You must check whether all components described in the JSON file are available in the depot for the target cluster. See Importing a Desired State Specification for information about how you can use a desired state specification for another cluster or standalone host.

Importing a Desired State Specification

To import a desired state of a cluster or a standalone host and assign it to another cluster or standalone host in the same or different vCenter Server instance:
  • For a cluster, call the importSoftwareSpec(cluster_ID, drafts_import_spec) method of the com.vmware.esx.settings.clusters.software.Drafts interface.
  • For a standalone host, call the importSoftwareSpec(host_ID, drafts_import_spec) method of the com.vmware.esx.settings.hosts.software.Drafts interface.
Pass as parameters the cluster or the standalone host ID, and an instance of the respective DraftsTypes.ImportSpec class. Use the instance of the import specification to describe the download source and the source type of the imported software specification. Depending on the location and the source type of the exported desired state, you can choose from the following import options:
  • Import a file from the vCenter Server or your local file system. Call the setFileId(fileId) method of the ImportSpec instance. Pass as argument the file ID of the software specification which was previously uploaded on the Jetty Web server running on the vCenter Server at https://<vcenter_FQDN>:9087/vum-fileupload URL. You can also use this option to import a specification file that resides on your local file system. Make sure you set the source type of the import specification to PUSH through the setSourceType(sourceType) method of the ImportSpec instance.
  • Import a file that resides on a URI location. Call the setLocation(location) method of the ImportSpec instance. Pass as argument the URI location of the software specification file. The software specification can be pulled from a URI location with one of the following schemes: file, http, or https. You can use this import mechanism only if you set the source type to SourceType.PULL.
  • Import a desired state as a JSON string. Call the setSoftwareSpec(softwareSpec) method of the ImportSpec instance. Pass as argument the JSON string representing the software specification you want to import. Use this mechanism only if you set the source type to SourceType.JSON_STRING.

Checking the Compliance Against the Desired State

Before applying a desired state on a cluster, you can scan all hosts in the cluster against the desired state and check the cluster compliance against the desired state. Before applying a desired state on a standalone host, you can scan the host and check its compliance against the desired state.

To check the compliance of all hosts in a cluster or of the single standalone host:
  • For a cluster, call the scan_Task(cluster_ID) method of the com.vmware.esx.settings.clusters.Software interface.
  • For a standalone host, call scan_Task(host_ID) method of the com.vmware.esx.settings.hosts.Software interface.
Pass as an parameter the cluster or the host identifier. The method compares the desired state against the current state of each host in the cluster or of the single host and as a result calculates the compliance.
You can retrieve the cluster or the standalone host compliance status by calling the get(cluster_ID) or get(host_ID) method of the respective Compliance interface and passing as argument the cluster or the standalone host ID. As a result you receive a com.vmware.esx.settings.ClusterCompliance or a com.vmware.esx.settings.HostCompliance object. You can use the ClusterCompliance or the HostCompliance instance to retrieve the following information:
  • The overall cluster compliance status regarding the target version of the components described within the cluster desired state.
  • The impact of applying the desired state on the cluster in case the cluster is non-compliant.
  • A list of all compliant hosts in the cluster.
  • A list of the incompatible hosts in the cluster.
  • A list of the non-compliant hosts in the cluster.
  • A list of the unavailable hosts which cannot be checked for compliance against the desired state.
  • The compliance status of each host in the cluster.
  • The notifications returned by the compliance check operation.
  • The time that the compliance check takes.
  • The ID of the committed draft for which the compliance check is performed. If the getCommit() method of the ClusterCompliance or the HostCompliance instance returns null, the compliance check is run against a draft software specification.
  • The compliance overall stage status of the cluster or the standalone host and is relevant when the compliance status of the cluster or the standalone host is NON_COMPLIANT.
  • The compliance of the OEM add-on on the standalone host with respect to the add-on in the desired state.
  • The compliance of the base image on the standalone host with respect to the base image in the desired state.
  • The compliance of all effective components and all components present on the standalone host in respect to the components in the desired state.
  • The compliance of all DPU devices on the standalone host with respect to the desired state.
  • The compliance of the hardware support on the standalone host with respect to the hardware support defined in the target state.
A cluster or a standalone host can have one of the following compliance statuses regarding the target versions:
  • COMPLIANT. The target versions of the components described in the desired state of the cluster or the standalone host are the same as the versions of the components currently present on the hosts in the cluster or on the standalone host.
  • NON_COMPLIANT. The desired state of the cluster or the standalone host describes components with higher versions than the versions of the components currently present on the hosts in the cluster or on the standalone host. Non-compliant clusters or hosts are those clusters or hosts which have orphaned VIBs, or components on the hosts that are not present in the desired state specification.
  • INCOMPATIBLE. One or more hosts in the cluster or in the standalone host have components with higher versions than the components described in the desired state specification.
  • UNAVAILABLE. The current state of one or more hosts in the cluster or of the standalone host cannot be retrieved and as a result the compliance check cannot be performed.

You can check the compliance impact of applying the desired state on a non-compliant cluster or a standalone host by calling the getImpact() method of the ClusterCompliance or the HostCompliance instance. A com.vmware.esx.settings.ComplianceImpact object is returned. Use it to retrieve information about the steps you must take to remediate the cluster or the standalone host successfully. You might need to reboot a host or put a host into maintenance mode to remediate the cluster or the standalone host successfully.