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 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 thecom.vmware.esx.settings.clusters.software.Draftsinterface
- For a standalone host,call the.create(host_ID)method of thecom.vmware.esx.settings.hosts.software.Draftsinterface
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 thecom.vmware.esx.settings.clusters.software.drafts.software.BaseImageinterface 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 thecom.vmware.esx.settings.hosts.software.drafts.software.BaseImageinterface 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
hostTo add an OEM add-on to a draft software specification:
- For a cluster,call the.set(cluster_ID,draft_ID,addon_spec)method of thecom.vmware.esx.settings.clusters.software.drafts.software.AddOninterface
- For a standalone host,call the.set(host_ID,draft_ID,addon_spec)method of thecom.vmware.esx.settings.hosts.software.drafts.software.AddOninterface
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 thecom.vmware.esx.settings.clusters.software.drafts.software.Componentsinterface
- For a standalone host,call the.set(host_ID, draft_ID, component_ID, version)method of thecom.vmware.esx.settings.hosts.software.drafts.software.Componentsinterface
component_ID
and version
arguments to the
draft, if it is missing. To remove a component from a draft, call the
. You can change multiple components in a draft by delete(cluster_ID,draft_ID,component_ID)
or
delete(host_ID,draft_ID,component_ID)
method of the
respective Components
interfacecalling 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 methodTo retrieve information about all components present in a draft, or a single component,
you can use the list methods of the respective
.Components
interfaceValidating 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
. 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. 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 IDTo check whether all hosts in the cluster or the standalone host are compliant with the
draft software specification,
call the
. 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. 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 IDCommitting 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
. 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.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