REST API - deploy

vcenter vm template library items: deploy

Deploys a virtual machine as a copy of the source virtual machine template contained in the library item specified by template_library_item. It uses the deployment specification in spec. If vcenter.vm_template.library_items.deploy_spec.powered_on and/or vcenter.vm_template.library_items.deploy_spec.guest_customization are specified, the server triggers the power on and/or guest customization operations, which are executed asynchronously. This operation was added in vSphere API 6.8.

Request:

HTTP request

POST https://{server}/rest/vcenter/vm-template/library-items/{template_library_item}?action=deploy

Path Parameters

Name	Type	Description
Required
template_library_item	string	identifier of the content library item containing the source virtual machine template to be deployed.

Request Body Structure:

{
    "spec" : {
        "disk_storage" : {
            "datastore" : "obj-103",
            "storage_policy" : {
                "type" : "USE_SPECIFIED_POLICY",
                "policy" : "obj-103"
            }
        },
        "hardware_customization" : {
            "cpu_update" : {
                "num_cpus" : 1,
                "num_cores_per_socket" : 1
            },
            "memory_update" : {
                "memory" : 1
            },
            "nics" : [
                {
                    "value" : {
                        "network" : "obj-103"
                    },
                    "key" : "obj-103"
                }
            ],
            "disks_to_remove" : [
                "obj-103",
                "obj-103"
            ],
            "disks_to_update" : [
                {
                    "value" : {
                        "capacity" : 1
                    },
                    "key" : "obj-103"
                }
            ]
        },
        "name" : "string",
        "description" : "string",
        "vm_home_storage" : {
            "datastore" : "obj-103",
            "storage_policy" : {
                "type" : "USE_SPECIFIED_POLICY",
                "policy" : "obj-103"
            }
        },
        "guest_customization" : {
            "name" : "string"
        },
        "disk_storage_overrides" : [
            {
                "value" : {
                    "datastore" : "obj-103",
                    "storage_policy" : {
                        "type" : "USE_SPECIFIED_POLICY",
                        "policy" : "obj-103"
                    }
                },
                "key" : "obj-103"
            }
        ],
        "placement" : {
            "cluster" : "obj-103",
            "folder" : "obj-103",
            "host" : "obj-103",
            "resource_pool" : "obj-103"
        },
        "powered_on" : true
    }
}

Request Body Parameters:

Name	Type	Description
bold = required
spec	deploy_spec	specification of how the virtual machine should be deployed.
spec.name	string	Name of the deployed virtual machine. This attribute was added in vSphere API 6.8.
spec.description	string	Description of the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If unset, the deployed virtual machine has the same description as the source library item.
spec.vm_home_storage	deploy_spec_vm_home_storage	Storage location for the deployed virtual machine's configuration and log files. This attribute was added in vSphere API 6.8. Optional. 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.
spec.vm_home_storage.datastore	string	Identifier of the datastore for the deployed virtual machine's configuration and log files. This attribute was added in vSphere API 6.8. Optional. This field is currently required. When `storage_policy` is also specified and is incompatible with the `datastore`, then the deployed virtual machine will be flagged as being out of compliance with the specified storage policy. . When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `Datastore`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `Datastore`.
spec.vm_home_storage.storage_policy	deploy_spec_vm_home_storage_policy	Storage policy for the deployed virtual machine's configuration and log files. This attribute was added in vSphere API 6.8. Optional. If unset, `datastore` must be specified and the deployed virtual machine's configuration and log files are created with the default storage policy associated with the `datastore`.
spec.vm_home_storage.storage_policy.type	string	Policy type to be used when creating the deployed virtual machine's configuration and log files. This attribute was added in vSphere API 6.8. Policy type for the deployed virtual machine's configuration and log files. This enumeration was added in vSphere API 6.8. Value is one of: USE_SPECIFIED_POLICY: Use the specified policy. This constant was added in vSphere API 6.8. USE_SOURCE_POLICY: Use the storage policy that is associated with the source virtual machine template's configuration and log files. This constant was added in vSphere API 6.8.
spec.vm_home_storage.storage_policy.policy	string	Identifier for the storage policy to use. This attribute was added in vSphere API 6.8. Optional. It is only relevant when type has value USE_SPECIFIED_POLICY. This field is optional and it is only relevant when the value of `type` is USE_SPECIFIED_POLICY.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `com.vmware.spbm.StorageProfile`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `com.vmware.spbm.StorageProfile`.
spec.disk_storage	deploy_spec_disk_storage	Storage specification for the deployed virtual machine's disks. This attribute was added in vSphere API 6.8. Optional. If both `disk_storage_overrides` and `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 `disk_storage_overrides` is unset and `disk_storage` is specified, all of the deployed virtual machine's disks are created with the storage spec specified by `disk_storage`. If `disk_storage_overrides` is specified and `disk_storage` is unset, disks with identifiers that are not in `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 `disk_storage_overrides` and `disk_storage` are specified, disks with identifiers that are not in `disk_storage_overrides` are created with the storage spec specified by `disk_storage`. .
spec.disk_storage.datastore	string	Identifier for the datastore associated the deployed virtual machine's disk. This attribute was added in vSphere API 6.8. Optional. This field is currently required. If `storage_policy` is also specified and is incompatible with the `datastore`, then the disk will be flagged as being out of compliance with the specified storage policy. . When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `Datastore`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `Datastore`.
spec.disk_storage.storage_policy	deploy_spec_disk_storage_policy	Storage policy for the deployed virtual machine's disk. This attribute was added in vSphere API 6.8. Optional. If unset, `datastore` must be specified and the deployed virtual machine's disk is created with the default storage policy associated with the `datastore`.
spec.disk_storage.storage_policy.type	string	Policy type to be used when creating the deployed virtual machine's disk. This attribute was added in vSphere API 6.8. Policy type for the deployed virtual machine's disk. This enumeration was added in vSphere API 6.8. Value is one of: USE_SPECIFIED_POLICY: Use the specified policy. This constant was added in vSphere API 6.8. USE_SOURCE_POLICY: Use the storage policy that is associated with the corresponding disk in the source virtual machine template. This constant was added in vSphere API 6.8.
spec.disk_storage.storage_policy.policy	string	Identifier of the storage policy to use. This attribute was added in vSphere API 6.8. Optional. It is only relevant when type has value USE_SPECIFIED_POLICY. This field is optional and it is only relevant when the value of `type` is USE_SPECIFIED_POLICY.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `com.vmware.spbm.StorageProfile`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `com.vmware.spbm.StorageProfile`.
spec.disk_storage_overrides	list	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. This attribute was added in vSphere API 6.8. Optional. If both `disk_storage_overrides` and `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 `disk_storage_overrides` is unset and `disk_storage` is specified, all of the deployed virtual machine's disks are created with the storage spec specified by `disk_storage`. If `disk_storage_overrides` is specified and `disk_storage` is unset, disks with identifiers that are not in `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 `disk_storage_overrides` and `disk_storage` are specified, disks with identifiers that are not in `disk_storage_overrides` are created with the storage spec specified by `disk_storage`. . When clients pass a value of this structure as a parameter, the key in the field key/value pairs 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 key/value pairs will be an identifier for the resource type: `com.vmware.vcenter.vm.hardware.Disk`.
spec.placement	deploy_placement_spec	Information used to place the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. 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. .
spec.placement.folder	string	Virtual machine folder into which the deployed virtual machine should be placed. This attribute was added in vSphere API 6.8. Optional. This field is currently required. If unset, the system will attempt to choose a suitable folder for the virtual machine; if a folder cannot be chosen, the virtual machine deployment operation will fail. . When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `Folder`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `Folder`.
spec.placement.resource_pool	string	Resource pool into which the deployed virtual machine should be placed. This attribute was added in vSphere API 6.8. Optional. If unset, the system will attempt to choose a suitable resource pool for the virtual machine; if a resource pool cannot be chosen, the virtual machine deployment operation will fail.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `ResourcePool`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `ResourcePool`.
spec.placement.host	string	Host onto which the virtual machine should be placed. If `host` and `resource_pool` are both specified, `resource_pool` must belong to `host`. If `host` and `cluster` are both specified, `host` must be a member of `cluster`. This attribute was added in vSphere API 6.8. Optional. This field may be unset if `resource_pool` or `cluster` is specified. If unset, the system will attempt to choose a suitable host for the virtual machine; if a host cannot be chosen, the virtual machine deployment operation will fail.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `HostSystem`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `HostSystem`.
spec.placement.cluster	string	Cluster onto which the deployed virtual machine should be placed. If `cluster` and `resource_pool` are both specified, `resource_pool` must belong to `cluster`. If `cluster` and `host` are both specified, `host` must be a member of `cluster`. This attribute was added in vSphere API 6.8. Optional. If `resource_pool` or `host` is specified, it is recommended that this field be unset.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `ClusterComputeResource`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `ClusterComputeResource`.
spec.powered_on	boolean	Specifies whether the deployed virtual machine should be powered on after deployment. This attribute was added in vSphere API 6.8. Optional. If unset, the virtual machine will not be powered on after deployment.
spec.guest_customization	guest_customization_spec	Guest customization spec to apply to the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If unset, the guest operating system is not customized after deployment.
spec.guest_customization.name	string	Name of the customization specification. This attribute was added in vSphere API 6.8. Optional. If unset, no guest customization is performed.
spec.hardware_customization	hardware_customization_spec	Hardware customization spec which specifies updates to the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If unset, the deployed virtual machine has the same hardware configuration as the source virtual machine template contained in the library item.
spec.hardware_customization.nics	list	Map of Ethernet network adapters to update. This attribute was added in vSphere API 6.8. Optional. If unset, all Ethernet adapters will remain connected to the same network as they were in the source virtual machine template. An Ethernet adapter with a MacAddressType of MANUAL will not change. An Ethernet adapter with a MacAddressType of GENERATED or ASSIGNED will receive a new address.When clients pass a value of this structure as a parameter, the key in the field key/value pairs must be an identifier for the resource type: `com.vmware.vcenter.vm.hardware.Ethernet`. When operations return a value of this structure as a result, the key in the field key/value pairs will be an identifier for the resource type: `com.vmware.vcenter.vm.hardware.Ethernet`.
spec.hardware_customization.disks_to_remove	string[]	Idenfiers of disks to remove from the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If unset, all disks will be copied.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: `com.vmware.vcenter.vm.hardware.Disk`. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: `com.vmware.vcenter.vm.hardware.Disk`.
spec.hardware_customization.disks_to_update	list	Disk update specification for individual disks in the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If unset, disks in the deployed virtual machine will have the same settings as the corresponding disks in the source virtual machine template contained in the library item.When clients pass a value of this structure as a parameter, the key in the field key/value pairs 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 key/value pairs will be an identifier for the resource type: `com.vmware.vcenter.vm.hardware.Disk`.
spec.hardware_customization.cpu_update	cpu_update_spec	CPU update specification for the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If {@term.unset}, the deployed virtual machine has the same CPU settings as the source virtual machine template contained in the library item.
spec.hardware_customization.cpu_update.num_cpus	long	Number of virtual processors in the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If {@term.unset}, the deployed virtual machine has the same CPU count as the source virtual machine template contained in the library item.
spec.hardware_customization.cpu_update.num_cores_per_socket	long	Number of cores among which to distribute CPUs in the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If {@term.unset}, the deployed virtual machine has the same number of cores per socket as the source virtual machine template contained in the library item.
spec.hardware_customization.memory_update	memory_update_spec	Memory update specification for the deployed virtual machine. This attribute was added in vSphere API 6.8. Optional. If {@term.unset}, the deployed virtual machine has the same memory settings as the source virtual machine template contained in the library item.
spec.hardware_customization.memory_update.memory	long	Size of a virtual machine's memory in MB. This attribute was added in vSphere API 6.8. Optional. If {@term.unset}, the deployed virtual machine has the same memory size as the source virtual machine template.

Response:

HTTP Status Code: 200

Representation:

{
"value" : "obj-103"
}

Response Type:

Name	Type	Description
bold = required
value	string	Identifier of the deployed virtual machine.

Errors:

HTTP Status Code	Type	Description
400	already_exists	if a virtual machine with the name specified by vcenter.vm_template.library_items.deploy_spec.name already exists.
500	error	if the system reports an error while responding to the request.
400	invalid_argument	if `spec` contains invalid arguments.
400	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.
404	not_found	if the library item specified by `template_library_item` cannot be found.
500	resource_inaccessible	if there was an error accessing the source virtual machine template contained in the library item specified by `template_library_item`.
503	service_unavailable	if any of the services involved in the operation are unavailable.
500	unable_to_allocate_resource	if there was an error in allocating any of the resources required by the operation.
401	unauthenticated	if the user that requested the operation cannot be authenticated.
403	unauthorized	if the user that requested the operation is not authorized to perform the operation.