REST API - clone-task
  1. Operations
  2. vcenter
  3. vm

vcenter VM: clone-task

Creates a virtual machine from an existing virtual machine.

. This operation was added in vSphere API 7.0.0.0.

Request:

HTTP request

POST https://{server}/rest/vcenter/vm?vmw-task=true&action=clone

Request Body Structure:

{
    "spec" : {
        "guest_customization_spec" : {
            "name" : "string"
        },
        "fallback_to_datastore_default_policy" : true,
        "power_on" : true,
        "vm_home_storage_policy" : {
            "policy" : "obj-103"
        },
        "name" : "string",
        "disks_to_remove" : [
            "obj-103",
            "obj-103"
        ],
        "source" : "obj-103",
        "placement" : {
            "cluster" : "obj-103",
            "folder" : "obj-103",
            "datastore" : "obj-103",
            "host" : "obj-103",
            "resource_pool" : "obj-103"
        },
        "disk_storage_policy" : {
            "policy" : "obj-103"
        },
        "disks_to_update" : [
            {
                "value" : {
                    "datastore" : "obj-103",
                    "storage_policy" : {
                        "policy" : "obj-103"
                    }
                },
                "key" : "obj-103"
            }
        ]
    }
}

Request Body Parameters:

Name Type Description
bold = required
spec clone_spec Virtual machine clone specification.
spec.source string Virtual machine to clone from. This attribute was added in vSphere API 7.0.0.0.

When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: VirtualMachine. When operations return a value of this structure as a result, the field will be an identifier for the resource type: VirtualMachine.
spec.name string Virtual machine name. This attribute was added in vSphere API 7.0.0.0.
spec.placement clone_placement_spec Virtual machine placement information. This attribute was added in vSphere API 7.0.0.0.

Optional. If this field is unset, the system will use the values from the source virtual machine. 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 result in disjoint placement the operation will fail.
spec.placement.folder string Virtual machine folder into which the cloned virtual machine should be placed. This attribute was added in vSphere API 7.0.0.0.

Optional. If field is unset, the system will use the virtual machine folder of the source virtual machine. If this results in a conflict due to other placement parameters, the virtual machine clone 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 cloned virtual machine should be placed. This attribute was added in vSphere API 7.0.0.0.

Optional. If field is unset, the system will use the resource pool of the source virtual machine. If this results in a conflict due to other placement parameters, the virtual machine clone 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 cloned 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 7.0.0.0.

Optional. If this field is unset, if resource_pool is unset, the cloned virtual machine will use the host of the source virtual machine. if resource_pool is set, and the target is a standalone host, the host is used. if resource_pool is set, and the target is a DRS cluster, a host will be picked by DRS. if resource_pool is set, and the target is a cluster without DRS, InvalidArgument will be thrown.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 into which the cloned 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 7.0.0.0.

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.placement.datastore string Datastore on which the cloned virtual machine's configuration state should be stored. This datastore will also be used for any virtual disks that are created as part of the virtual machine clone operation unless individually overridden. This attribute was added in vSphere API 7.0.0.0.

Optional. If field is unset, the system will use the datastore of the source virtual machine.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.disks_to_remove string[] Set of Disks to Remove. This attribute was added in vSphere API 7.0.0.0.

Optional. If unset, all disks will be copied. If the same identifier is in vcenter.VM.clone_spec.disks_to_update InvalidArgument fault will be returned.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.disks_to_update list Map of Disks to Update. This attribute was added in vSphere API 7.0.0.0.

Optional. If unset, all disks will copied to the datastore specified in the vcenter.VM.clone_placement_spec.datastore field of vcenter.VM.clone_spec.placement. If the same identifier is in vcenter.VM.clone_spec.disks_to_remove InvalidArgument fault will be thrown.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.vm_home_storage_policy storage_policy_spec Storage policy to be associated with the virtual machine home (which contains the configuration and log files). Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If unset, the cloned virtual machine home will be associated with a storage policy based the rules described for the clone operation.
spec.vm_home_storage_policy.policy string Identifier of the storage policy which should be associated with the virtual machine. This attribute was added in vSphere API 6.7.

When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: com.vmware.vcenter.StoragePolicy. When operations return a value of this structure as a result, the field will be an identifier for the resource type: com.vmware.vcenter.StoragePolicy.
spec.disk_storage_policy storage_policy_spec Storage policy to be associated with the virtual machine disks. If set, each of the cloned virtual disks is assigned the specified storage policy, unless it is overwritten in vcenter.VM.clone_spec.disks_to_update. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If unset, the cloned disks will be associated with a storage policy based the rules described for the clone operation.
spec.disk_storage_policy.policy string Identifier of the storage policy which should be associated with the virtual machine. This attribute was added in vSphere API 6.7.

When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: com.vmware.vcenter.StoragePolicy. When operations return a value of this structure as a result, the field will be an identifier for the resource type: com.vmware.vcenter.StoragePolicy.
spec.fallback_to_datastore_default_policy boolean Flag used by the server to auto assign storage policy when a target storage policy is not explicitly specified for the operation and the source virtual machine storage policy is not compatible with target datastore. If flag is set to true, the server will use the default storage policy of the target datastore. Otherwise, the server will throw an error for the operation. See also the storage policy assignment rules for the clone operation. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If unset, the default value is false, the server will throw an error if source policy is not compatible with the target datastore.
spec.power_on boolean Attempt to perform a vcenter.VM.clone_spec.power_on after clone. This attribute was added in vSphere API 7.0.0.0.

Optional. If unset, the virtual machine will not be powered on.
spec.guest_customization_spec guest_customization_spec Guest customization spec to apply to the virtual machine after the virtual machine is deployed. This attribute was added in vSphere API 7.0.0.0.

Optional. If unset, the guest operating system is not customized after clone.
spec.guest_customization_spec.name string Name of the customization specification. This attribute was added in vSphere API 7.0.0.0.

Optional. If unset, no guest customization is performed.

Response:

HTTP Status Code: 200

Representation:

{
    "value" : "obj-103"
}

Response Type:

Name Type Description
bold = required
value string ID of newly-created virtual machine.

Errors:

HTTP Status Code Type Description
400 already_exists if a virtual machine with the specified name already exists.
500 error if the system reports an error while responding to the request.
400 invalid_argument if any of the specified parameters are invalid.
404 not_found if any of the resources specified in spec could not be found
500 resource_inaccessible if a specified resource (eg. host) is not accessible.
503 service_unavailable if the system is unable to communicate with a service to complete the request.
500 unable_to_allocate_resource if any of the resources needed to clone the virtual machine could not be allocated.
401 unauthenticated if the user can not be authenticated.
403 unauthorized if the user doesn't have the required privileges.