VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Working with Desired Software States

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.

Content feedback and comments