This API has a deprecated equivalent from v7.0U1.
Deploy Library Items
Deploys a virtual machine as a copy of the source virtual machine template contained in the library item specified by templateLibraryItem. It uses the deployment specification in spec. If LibraryItems.DeploySpec.powered-on and/or LibraryItems.DeploySpec.guest-customization are specified, the server triggers the power on and/or guest customization operations, which are executed asynchronously. if you do not have all of the privileges described as follows: - Operation execution requires System.Read. - The resource com.vmware.content.library.Item referenced by the parameter templateLibraryItem requires VirtualMachine.Provisioning.DeployTemplate. - The resource Datastore referenced by the attribute LibraryItems.DeploySpecVmHomeStorage.datastore requires System.Read. - The resource com.vmware.spbm.StorageProfile referenced by the attribute LibraryItems.DeploySpecVmHomeStoragePolicy.policy requires System.Read. - The resource Datastore referenced by the attribute LibraryItems.DeploySpecDiskStorage.datastore requires System.Read. - The resource com.vmware.spbm.StorageProfile referenced by the attribute LibraryItems.DeploySpecDiskStoragePolicy.policy requires System.Read. - The resource com.vmware.vcenter.vm.hardware.Disk referenced by the map key of attribute LibraryItems.DeploySpec.disk-storage-overrides requires System.Read. - The resource Folder referenced by the attribute LibraryItems.DeployPlacementSpec.folder requires System.Read. - The resource ResourcePool referenced by the attribute LibraryItems.DeployPlacementSpec.resource-pool requires System.Read. - The resource HostSystem referenced by the attribute LibraryItems.DeployPlacementSpec.host requires System.Read. - The resource ClusterComputeResource referenced by the attribute LibraryItems.DeployPlacementSpec.cluster requires System.Read. - The resource com.vmware.vcenter.vm.hardware.Ethernet referenced by the map key of attribute LibraryItems.HardwareCustomizationSpec.nics requires System.Read. - The resource Network referenced by the attribute LibraryItems.EthernetUpdateSpec.network requires System.Read. - The resource com.vmware.vcenter.vm.hardware.Disk referenced by the attribute LibraryItems.HardwareCustomizationSpec.disks-to-remove requires System.Read. - The resource com.vmware.vcenter.vm.hardware.Disk referenced by the map key of attribute LibraryItems.HardwareCustomizationSpec.disks-to-update requires System.Read.
Request
URLURL
https://{api_host}/api/vcenter/vm-template/library-items/{template_library_item}?action=deploy
Path Parameters
Path Parameters
string
template_library_item
Required
identifier of the content library item containing the source virtual machine template to be deployed. The parameter must be an identifier for the resource type: com.vmware.content.library.Item.
Header Parameters
Header Parameters
string
vmware-api-session-id
Required
Required session ID, acquired from Create Session API under CIS product
vmware-api-session-id example
"b00db39f948d13ea1e59b4d6fce56389"
Request Body
Request Body
VmTemplateLibraryItemsDeploySpec of mimetype application/json
Required
specification of how the virtual machine should be deployed.
{
"name": "string",
"placement": {
"folder": "string"
}
}
placement
Required
Information used to place the deployed virtual machine. This field is currently required. In the future, if this field is unset, the system will use the values from the source virtual machine template contained in the library item. If specified, each field will be used for placement. If the fields result in disjoint placement, the operation will fail. If the fields along with the placement values of the source virtual machine template result in disjoint placement, the operation will fail.
string
name
Required
Name of the deployed virtual machine.
disk_storage
Optional
Storage specification for the deployed virtual machine’s disks. If both LibraryItems.DeploySpec.disk-storage-overrides and LibraryItems.DeploySpec.disk-storage are unset, the deployed virtual machine’s disks are created with the same storage spec as the corresponding disks in the source virtual machine template contained in the library item. If LibraryItems.DeploySpec.disk-storage-overrides is unset and LibraryItems.DeploySpec.disk-storage is specified, all of the deployed virtual machine’s disks are created with the storage spec specified by LibraryItems.DeploySpec.disk-storage.
If LibraryItems.DeploySpec.disk-storage-overrides is specified and LibraryItems.DeploySpec.disk-storage is unset, disks with identifiers that are not in LibraryItems.DeploySpec.disk-storage-overrides are created with the same storage spec as the corresponding disks in the source virtual machine template contained in the library item.
If both LibraryItems.DeploySpec.disk-storage-overrides and LibraryItems.DeploySpec.disk-storage are specified, disks with identifiers that are not in LibraryItems.DeploySpec.disk-storage-overrides are created with the storage spec specified by LibraryItems.DeploySpec.disk-storage.
disk_storage_overrides
Optional
Storage specification for individual disks in the deployed virtual machine. This is specified as a mapping between disk identifiers in the source virtual machine template contained in the library item and their storage specifications. If both LibraryItems.DeploySpec.disk-storage-overrides and LibraryItems.DeploySpec.disk-storage are unset, the deployed virtual machine’s disks are created with the same storage spec as the corresponding disks in the source virtual machine template contained in the library item. If LibraryItems.DeploySpec.disk-storage-overrides is unset and LibraryItems.DeploySpec.disk-storage is specified, all of the deployed virtual machine’s disks are created with the storage spec specified by LibraryItems.DeploySpec.disk-storage.
If LibraryItems.DeploySpec.disk-storage-overrides is specified and LibraryItems.DeploySpec.disk-storage is unset, disks with identifiers that are not in LibraryItems.DeploySpec.disk-storage-overrides are created with the same storage spec as the corresponding disks in the source virtual machine template contained in the library item.
If both LibraryItems.DeploySpec.disk-storage-overrides and LibraryItems.DeploySpec.disk-storage are specified, disks with identifiers that are not in LibraryItems.DeploySpec.disk-storage-overrides are created with the storage spec specified by LibraryItems.DeploySpec.disk-storage.
When clients pass a value of this structure as a parameter, the key in the field map must be an identifier for the resource type: com.vmware.vcenter.vm.hardware.Disk. When operations return a value of this structure as a result, the key in the field map will be an identifier for the resource type: com.vmware.vcenter.vm.hardware.Disk.
guest_customization
Optional
Guest customization spec to apply to the deployed virtual machine. If unset, the guest operating system is not customized after deployment.
hardware_customization
Optional
Hardware customization spec which specifies updates to the deployed virtual machine. If unset, the deployed virtual machine has the same hardware configuration as the source virtual machine template contained in the library item.
string
description
Optional
Description of the deployed virtual machine. If unset, the deployed virtual machine has the same description as the source library item.
boolean
powered_on
Optional
Specifies whether the deployed virtual machine should be powered on after deployment. If unset, the virtual machine will not be powered on after deployment.
vm_home_storage
Optional
Storage location for the deployed virtual machine’s configuration and log files. If unset, the deployed virtual machine’s configuration and log files are created with the same storage spec as the source virtual machine template’s configuration and log files.
Authentication
This operation uses the following authentication methods.
Response
Response
Response BodyResponse Body
200 OK returns
string
of type application/json
Identifier of the deployed virtual machine. The result will be an identifier for the resource type: VirtualMachine.
Errors
400
com.vmware.vapi.std.errors.already_exists : if a virtual machine with the name specified by LibraryItems.DeploySpec.name already exists. | com.vmware.vapi.std.errors.invalid_argument : if spec contains invalid arguments. | com.vmware.vapi.std.errors.not_allowed_in_current_state : if either a specified host or a specified datastore is in an invalid state for the deployment, such as maintenance mode.
401
com.vmware.vapi.std.errors.unauthenticated : if the user that requested the operation cannot be authenticated.
403
com.vmware.vapi.std.errors.unauthorized : if the user that requested the operation is not authorized to perform the operation.
404
com.vmware.vapi.std.errors.not_found : if the library item specified by templateLibraryItem cannot be found. if any resource specified by a field of the LibraryItems.DeploySpec structure, specified by spec cannot be found.
500
com.vmware.vapi.std.errors.error : if the system reports an error while responding to the request. | com.vmware.vapi.std.errors.resource_inaccessible : if there was an error accessing the source virtual machine template contained in the library item specified by templateLibraryItem. if there an error accessing any of the resources specified in the spec. | com.vmware.vapi.std.errors.unable_to_allocate_resource : if there was an error in allocating any of the resources required by the operation.
503
com.vmware.vapi.std.errors.service_unavailable : if any of the services involved in the operation are unavailable.
default
‘Default’ means this response is used for all HTTP codes that are not covered individually for this operation.
Code Samples
PowerCLI Client SDK Example
$VmTemplateLibraryItemsDeployPlacementSpec = Initialize-VmTemplateLibraryItemsDeployPlacementSpec -Folder "MyFolder"
$VmTemplateLibraryItemsDeploySpec = Initialize-VmTemplateLibraryItemsDeploySpec -Name "MyName" -Placement $VmTemplateLibraryItemsDeployPlacementSpec
Invoke-DeployTemplateLibraryItemLibraryItems -TemplateLibraryItem "MyTemplateLibraryItem" -VmTemplateLibraryItemsDeploySpec $VmTemplateLibraryItemsDeploySpec
PowerCLI Client SDK All Parameters Example
$VmTemplateLibraryItemsDeploySpecVmHomeStoragePolicy = Initialize-VmTemplateLibraryItemsDeploySpecVmHomeStoragePolicy -Type "USE_SPECIFIED_POLICY" -Policy "MyPolicy"
$VmTemplateLibraryItemsDeploySpecVmHomeStorage = Initialize-VmTemplateLibraryItemsDeploySpecVmHomeStorage -Datastore "MyDatastore" -StoragePolicy $VmTemplateLibraryItemsDeploySpecVmHomeStoragePolicy
$VmTemplateLibraryItemsDeploySpecDiskStoragePolicy = Initialize-VmTemplateLibraryItemsDeploySpecDiskStoragePolicy -Type "USE_SPECIFIED_POLICY" -Policy "MyPolicy"
$VmTemplateLibraryItemsDeploySpecDiskStorage = Initialize-VmTemplateLibraryItemsDeploySpecDiskStorage -Datastore "MyDatastore" -StoragePolicy $VmTemplateLibraryItemsDeploySpecDiskStoragePolicy
$VmTemplateLibraryItemsDeployPlacementSpec = Initialize-VmTemplateLibraryItemsDeployPlacementSpec -Folder "MyFolder" -ResourcePool "MyResourcePool" -VarHost "MyVarHost" -Cluster "MyCluster"
$VmTemplateLibraryItemsGuestCustomizationSpec = Initialize-VmTemplateLibraryItemsGuestCustomizationSpec -Name "MyName"
$VmTemplateLibraryItemsEthernetUpdateSpec = Initialize-VmTemplateLibraryItemsEthernetUpdateSpec -Network "MyNetwork"
$VmTemplateLibraryItemsDiskUpdateSpec = Initialize-VmTemplateLibraryItemsDiskUpdateSpec -Capacity 0
$VmTemplateLibraryItemsCpuUpdateSpec = Initialize-VmTemplateLibraryItemsCpuUpdateSpec -NumCpus 0 -NumCoresPerSocket 0
$VmTemplateLibraryItemsMemoryUpdateSpec = Initialize-VmTemplateLibraryItemsMemoryUpdateSpec -Memory 0
$VmTemplateLibraryItemsHardwareCustomizationSpec = Initialize-VmTemplateLibraryItemsHardwareCustomizationSpec -Nics @{ key_example = $VmTemplateLibraryItemsEthernetUpdateSpec } -DisksToRemove "MyDisksToRemove" -DisksToUpdate @{ key_example = $VmTemplateLibraryItemsDiskUpdateSpec } -CpuUpdate $VmTemplateLibraryItemsCpuUpdateSpec -MemoryUpdate $VmTemplateLibraryItemsMemoryUpdateSpec
$VmTemplateLibraryItemsDeploySpec = Initialize-VmTemplateLibraryItemsDeploySpec -Name "MyName" -Description "MyDescription" -VmHomeStorage $VmTemplateLibraryItemsDeploySpecVmHomeStorage -DiskStorage $VmTemplateLibraryItemsDeploySpecDiskStorage -DiskStorageOverrides @{ key_example = $VmTemplateLibraryItemsDeploySpecDiskStorage } -Placement $VmTemplateLibraryItemsDeployPlacementSpec -PoweredOn $false -GuestCustomization $VmTemplateLibraryItemsGuestCustomizationSpec -HardwareCustomization $VmTemplateLibraryItemsHardwareCustomizationSpec
Invoke-DeployTemplateLibraryItemLibraryItems -TemplateLibraryItem "MyTemplateLibraryItem" -VmTemplateLibraryItemsDeploySpec $VmTemplateLibraryItemsDeploySpec
cURL Command
curl -X POST -H "vmware-api-session-id: b00db39f948d13ea1e59b4d6fce56389" -H "Content-Type: application/json" -d '{"description":"string","disk_storage":{"datastore":"string","storage_policy":{"policy":"string","type":"USE_SPECIFIED_POLICY"}},"disk_storage_overrides":{"key":{"datastore":"string","storage_policy":{"policy":"string","type":"USE_SPECIFIED_POLICY"}}},"guest_customization":{"name":"string"},"hardware_customization":{"cpu_update":{"num_cores_per_socket":0,"num_cpus":0},"disks_to_remove":["string"],"disks_to_update":{"key":{"capacity":0}},"memory_update":{"memory":0},"nics":{"key":{"network":"string"}}},"name":"string","placement":{"cluster":"string","folder":"string","host":"string","resource_pool":"string"},"powered_on":false,"vm_home_storage":{"datastore":"string","storage_policy":{"policy":"string","type":"USE_SPECIFIED_POLICY"}}}' https://{api_host}/api/vcenter/vm-template/library-items/{template_library_item}?action=deploy
Vendor Extensions
This operation contains the following vendor extensions defined in the spec:
x-vmw-doc-deprecated-method: post
x-vmw-doc-deprecated-path: /rest/vcenter/vm-template/library-items/{template_library_item}?action=deploy
x-vmw-doc-operation: deploy
Availability
Added in 7.0U2
