VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Working with Draft Software Specifications

You create a draft software specification to describe the components of the desired state that you want to apply on a cluster or a standalone host.
The draft software specification is the working copy of the desired software state. Only one user at a time is allowed to edit a single draft for a cluster or a standalone host. Before saving the changes to the edited draft version, you can validate the content of the draft.
Drafts Workflow for a Cluster
A workflow diagram that visualizes the steps you need to take to apply a desired software specification to a cluster.
A typical workflow for working with draft software specifications starts with creating a draft software specification for a specific cluster or a standalone host. If the cluster or the standalone host already have a software specification defined, this action takes the latest committed draft and you can edit its contents according to your needs. If the cluster or the standalone host have no software specification created yet, this method creates an empty draft. The only mandatory item for a draft is a base image of a specific version.
After you complete adding components, an add-on, and a base image, you can save your changes by committing the draft. This operation results in setting the committed draft as the current desired state of the cluster or the standalone host. Before committing the draft software specification, you can validate the contents of the draft or check whether all hosts in the cluster or the single standalone host are compliant with the draft.
If the commit operation is successful, the draft becomes the desired state for the cluster or the standalone host. You can now export the software specification and use it, for example, in a ROBO cluster scenario or another standalone host. You can also validate the compliance of the hosts in the cluster or the standalone host against the desired state and then apply the software specification, if feasible.

Creating a Draft Software Specification

To describe the components of a desired state for a cluster or a standalone host, create a draft software specification and save the desired state when ready.
To edit an existing desired state or to create an empty draft software specification:
  • For a cluster,
    call the
    create(cluster_ID)
     method of the
    com.vmware.esx.settings.clusters.software.Drafts
     interface
    .
  • For a standalone host,
    call the
    create(host_ID)
     method of the
    com.vmware.esx.settings.hosts.software.Drafts
     interface
    .
Pass the cluster ID or the host ID as an argument to the respective method.
As a result, you receive a draft ID which you can use to add a base image, an add-on, or some components to the draft.

Editing a Draft Software Specification

After you have created a draft software specification, use the
vSphere Automation
API to edit its items.
To set a base image to a draft software specification:
  • For a cluster,
    call the
    set(cluster_ID, draft_ID, base_image_spec)
     method of the
    com.vmware.esx.settings.clusters.software.drafts.software.BaseImage
     interface and pass as arguments the cluster and the draft IDs, and a base image specification
    .
  • For a standalone host,
    call the
    set(host_ID, draft_ID, base_image_spec)
     method of the
    com.vmware.esx.settings.hosts.software.drafts.software.BaseImage
     interface and pass as arguments the standalone host and draft ID, and a base image specification
    .
If the draft contains a base image, this method overwrites the existing image. The base image specification contains the version of the bootable
ESXi
 that must be included in the desired state. To retrieve details about the base image that is currently present in a draft,
call the
get(cluster_ID,draft_ID)
 or
get(host_ID, draft_ID)
 methods of the
com.vmware.esx.settings.clusters.software.drafts.software.BaseImage
 interface. Pass as arguments the cluster or the standalone host ID and the draft ID. Use the returned
com.vmware.esx.settings.BaseImageInfo
 object to query the version, display name and version, and the release date of the
ESXi
 host
.
To add an OEM add-on to a draft software specification:
  • For a cluster,
    call the
    set(cluster_ID,draft_ID,addon_spec)
     method of the
    com.vmware.esx.settings.clusters.software.drafts.software.AddOn
     interface
    .
  • For a standalone host,
    call the
    set(host_ID,draft_ID,addon_spec)
     method of the
    com.vmware.esx.settings.hosts.software.drafts.software.AddOn
     interface
    .
Pass as arguments to these methods the cluster or the standalone host ID, the draft ID, and the add-on specification. If you want to remove an add-on from a draft,
call the
delete(cluster_ID,draft_ID)
 or
delete(host_ID,draft_ID)
 method of the respective
AddOn
 interface and pass as arguments the cluster or the standalone host ID, and the draft ID
.
You can add a component, change the version, or delete an existing component from a draft software specification. To change the version of a component included in a draft:
  • For a cluster,
    call the
    set(cluster_ID,draft_ID,component_ID,version)
     method of the
    com.vmware.esx.settings.clusters.software.drafts.software.Components
     interface
    .
  • For a standalone host,
    call the
    set(host_ID, draft_ID, component_ID, version)
     method of the
    com.vmware.esx.settings.hosts.software.drafts.software.Components
     interface
    .
As a result, you add the component specified with the
component_ID
 and
version
 arguments to the draft, if it is missing. To remove a component from a draft,
call the
delete(cluster_ID,draft_ID,component_ID)
 or
delete(host_ID,draft_ID,component_ID)
 method of the respective
Components
 interface
. You can change multiple components in a draft by
calling the
update(cluster_ID,draft_ID,update_spec)
 or
update(host_ID,draft_ID,update_spec)
 method of the respective
Components
 interface. To specify the components you want to remove, add, or update for a draft, pass a cluster or a host
ComponentsTypes.UpdateSpec
 instance as an argument to the update method
.
To retrieve information about all components present in a draft, or a single component,
you can use the list methods of the respective
Components
 interface
.

Validating the Draft Software Specification

Before saving a draft and turning it into a desired state for a cluster or a standalone host, you can check whether the specification is complete and valid. You can also check whether the draft specification drifts in any way from the current state of the cluster or the host.
The
Drafts
 service offers two methods for validating the draft software specification. To check whether a draft is complete and there are no conflicts between the draft components, or unresolved dependencies,
call the
validate_Task(cluster_ID,draft_ID)
 or
validate_Task(host_ID,draft_ID)
 method of the respective
Drafts
 interface. Pass as arguments to the method the cluster or the standalone host ID, and the draft ID
. You validate whether there were any other drafts committed for this cluster or standalone host, which can make the current commit operation invalid. The method also validates whether all components defined in the software specification are available in the depot metadata. This method does not run compliance checks against the cluster or the standalone host.
To check whether all hosts in the cluster or the standalone host are compliant with the draft software specification,
call the
scan_Task(cluster_ID,draft_ID)
 or
scan_Task(host_ID,draft_ID)
 method of the respective
Drafts
 interface. Pass as arguments to this method the cluster or the standalone host ID, and the draft ID
. This method results in running a comparison between the draft specification and the current state of each host in the cluster or the current state of the standalone host.

Committing the Draft Software Specification

When you commit a draft software specification, it becomes the desired state for the cluster or the standalone host.
To save the draft that you created for a cluster or a standalone host,
call the
commit_Task(cluster_ID,draft_ID,draft_commit_spec)
 or
commit_Task(host_ID, draft_ID, draft_commit_spec)
 method of the respective
Drafts
 interface
. The Image Manager component runs a validation check before the draft gets saved to the database. This method returns an identifier of the commit operation. You can use the ID to retrieve information about a specific commit such as the author of the commit operation, the time when the draft was committed, and so on.

Content feedback and comments