Vcenter Ovfs deploy$Task
Deploy an OVF on a resource pool.
Deployment creates a new Virtual Machine(VM) or Virtual Appliance(VApp), from an OVF located on a web-server, in the specified folder and attached to a resource pool.
The descriptor OVF is downloaded, parsed and its validity is verified against the provided deployment constraints(if any). The files referenced in the descriptor are then downloaded and processed. In case of OVA, files are extracted and processed. If file-paths in OVF are not absolute then they are assumed to be relative to the descriptor URL.
The import process consists of two parts:
- Create the VMs and/or VApps that make up the entity.
- Upload virtual disk contents.
In part 1: The server creates all inventory objects. If an error occurs while creating inventory objects the import process is aborted, task reflects a failure.
In part 2: The server transfers disk contents using from the URL location.
When the server is done transferring disks, if there are no Guest customization or PowerOn specified the task completes, else those requested operations are performed.
If the import process fails or times out, all created inventory objects are removed, including all virtual disks. Note: if VC is abruptly stopped in the middle of this task cleanup might not be able to happen in time.
This operation only works if the folder's childType includes required VM privilege VirtualMachine.Inventory.Create.
By default Pull mode is leveraged unless user specifies otherwise. On vCenter server the privilege VApp.PullFromUrls is required if default behaviour is performed.
This operation was added in vSphere API 9.0.0.0.
Returns an authorization error if you do not have all of the privileges described as follows:
- The resource
ResourcePoolreferenced by the property Vcenter Ovfs DeploySpec.resource_pool requiresResource.AssignVMToPoolandVApp.Import. - The resource
Datastorereferenced by the property Vcenter Ovfs DatastoreInfo.datastore requiresDatastore.AllocateSpace. - The resource
Folderreferenced by the property Vcenter Ovfs DeploySpec.folder requiresVirtualMachine.Inventory.CreateandVApp.Import.
Specification for deployment.
Show optional properties
{
"url": "string",
"name": "string",
"vm_home_datastore": {}
}{
"url": "string",
"resource_pool": "string",
"folder": "string",
"name": "string",
"host_system": "string",
"network_mapping": {
"network_mapping": {
"net_type": "string",
"network": "string"
}
},
"vm_home_datastore": {
"datastore": "string"
},
"disk_provisioning": "string",
"pull_from_esx": false,
"signature_required": false,
"skip_manifest_check": false,
"power_on": false,
"custom_http_headers": {
"custom_http_headers": "string"
},
"custom_properties": {
"custom_properties": "string"
},
"source_certificate": "string",
"deployment_option": "string"
}The HTTP location of the source OVF files or OVA.
This property was added in vSphere API 9.0.0.0.
The resource pool where the VM or vApp will deploy. Currently required but in the future versions may become optional.
This property was added in vSphere API 9.0.0.0.
if missing or null or empty, the deployment will fail.
When clients pass a value of this schema as a parameter, the property must be an identifier for the resource type: ResourcePool. When operations return a value of this schema as a response, the property will be an identifier for the resource type: ResourcePool.
The folder where the VirtualMachine will be placed.
This property was added in vSphere API 9.0.0.0.
if missing or null or empty, the folder will be set to vmFolder in the datacenter where the resource pool is.
When clients pass a value of this schema as a parameter, the property must be an identifier for the resource type: Folder. When operations return a value of this schema as a response, the property will be an identifier for the resource type: Folder.
The name of the VM or vApp being deployed as specified by an OVF.
This property was added in vSphere API 9.0.0.0.
The identifier of the host being deployed to.
This property was added in vSphere API 9.0.0.0.
If missing or null, a suitable host will be picked if possible, meeting datastore and network constraints.
When clients pass a value of this schema as a parameter, the property must be an identifier for the resource type: HostSystem. When operations return a value of this schema as a response, the property will be an identifier for the resource type: HostSystem.
The networkMapping defines user choices for mapping of a network as specified by the OVF descriptor to a Network in the inventory.
This property was added in vSphere API 9.0.0.0.
If missing or null, no network mapping is used.
The datastore selection for VM's home directory.
This property was added in vSphere API 9.0.0.0.
The optional disk provisioning type used upon deployment. If set all the disks in the deployed OVF will have the same specified disk type (e.g., thin provisioned).
For more information see: Vcenter Ovfs DiskProvisioningType.
This property was added in vSphere API 9.0.0.0.
If missing or null, the type will be set to thick.
Use Push mode for transferring VM files to ESX. Push mode transfers files from source to ESXi, whereas in Pull mode ESX "pulls" the files directly from source. The user needs privilege VApp.PullFromUrls in vCenter to use Pull mode.
This property was added in vSphere API 9.0.0.0.
If missing or null, the default is set to Pull mode.
Require that the OVF package includes both a certificate (.cert) file and a manifest (.mf) file. The certificate file contains a vendor-supplied public key and the signature of the manifest file as signed with the vendor-supplied private key.
This property was added in vSphere API 9.0.0.0.
If missing or null, the default is set to false.
Skip manifest validation. The manifest validation involves validating format and content of the manifest file. In Push mode of deployment all SHA entries present in the manifest file are validated against SHA digest of transferred files. If value is true and manifest file is not present a warning is generated.
This property was added in vSphere API 9.0.0.0.
If missing or null, the default is set to false.
Whether to power on the deployed entity.
This property was added in vSphere API 9.0.0.0.
If missing or null, the default is set to false.
Use this optional field to specify any custom headers required by the source server, including authenticating headers.
This property was added in vSphere API 9.0.0.0.
If missing or null, no headers are used to access source.
These parameters will apply to OVF Properties to customize the guest OS after it is deployed. These parameters specify values for corresponding ovf:Property flags. Example: if ovf:Property has ovf:key="ip" and desrired value is "1.2.3.4" then an entry would be added which would map "ip" to "1.2.3.4".
This property was added in vSphere API 9.0.0.0.
If missing or null, no customization is done.
Optionally used for HTTPS source validation. The source is the location where the OVF/OVA files are located. The source server certificate in PEM format.
This property was added in vSphere API 9.0.0.0.
If missing or null, no certificate is used.
The key of the chosen deployment option. If empty, the default option is chosen. The list of available deployment options can optionally be specified in the OVF file being deployed and this key specifies which one to use for deployment from that list.
This property was added in vSphere API 9.0.0.0.
The Vcenter Ovfs DeployResult of the newly created entity.
Vapi Std Errors InvalidArgument If any of the specified parameters is invalid.
Vapi Std Errors UnverifiedPeer If vCenter Server cannot validate the certificate of the server that supplies the OVF file.
The value of the data property of Vapi Std Errors Error will be a schema that contains all the properties defined in CertificateInfo.
"Vapi Std Errors Error Object"Stack of one or more localizable messages for human error consumers.
The message at the top of the stack (first in the list) describes the error from the perspective of the operation the client invoked.
Each subsequent message in the stack describes the "cause" of the prior message.
Data to facilitate clients responding to the operation reporting a standard error to indicating that it was unable to complete successfully.
Operations may provide data that clients can use when responding to errors. Since the data that clients need may be specific to the context of the operation reporting the error, different operations that report the same error may provide different data in the error. The documentation for each each operation will describe what, if any, data it provides for each error it reports.
The Vapi Std Errors ArgumentLocations, Vapi Std Errors FileLocations, and Vapi Std Errors TransientIndication schemas are intended as possible values for this property. Vapi Std DynamicID may also be useful as a value for this property (although that is not its primary purpose). Some resources may provide their own specific schemas for use as the value of this property when reporting errors from their operations.
Some operations will not set this property when reporting errors.
Discriminator field to help API consumers identify the structure type.
For more information see: Vapi Std Errors Error Type.
This property was added in vSphere API 6.7.2.
Can be missing or null for compatibility with preceding implementations.
if the user can not be authenticated.
"Vapi Std Errors Unauthenticated Object"Indicates the authentication challenges applicable to the target API provider. It can be used by a client to discover the correct authentication scheme to use. The exact syntax of the value is defined by the specific provider, the protocol and authentication schemes used.
For example, a provider using REST may adhere to the WWW-Authenticate HTTP header specification, RFC7235, section 4.1. In this case an example challenge value may be: SIGN realm="27da1358-2ba4-11e9-b210-d663bd873d93",sts="http://vcenter/sso?vsphere.local", Basic realm="vCenter"
This property was added in vSphere API 7.0.0.0.
This property is optional because it was added in a newer version than its parent node.
If the resource pool is not found.
"Vapi Std Errors NotFound Object"If the system reports an error while responding to the request.
"Vapi Std Errors Error Object"Stack of one or more localizable messages for human error consumers.
The message at the top of the stack (first in the list) describes the error from the perspective of the operation the client invoked.
Each subsequent message in the stack describes the "cause" of the prior message.
Data to facilitate clients responding to the operation reporting a standard error to indicating that it was unable to complete successfully.
Operations may provide data that clients can use when responding to errors. Since the data that clients need may be specific to the context of the operation reporting the error, different operations that report the same error may provide different data in the error. The documentation for each each operation will describe what, if any, data it provides for each error it reports.
The Vapi Std Errors ArgumentLocations, Vapi Std Errors FileLocations, and Vapi Std Errors TransientIndication schemas are intended as possible values for this property. Vapi Std DynamicID may also be useful as a value for this property (although that is not its primary purpose). Some resources may provide their own specific schemas for use as the value of this property when reporting errors from their operations.
Some operations will not set this property when reporting errors.
Discriminator field to help API consumers identify the structure type.
For more information see: Vapi Std Errors Error Type.
This property was added in vSphere API 6.7.2.
Can be missing or null for compatibility with preceding implementations.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name:"string","url:"string","vm_home_datastore":"{}"}' https://{api_host}/api/vcenter/ovfs?action=deploy&vmw-task=true