To allow greater flexibility when modifying template properties during instantiation, use SourcedItem instead of SourcedVmInstantiationParams when specifying instantiation details in InstantiateVAppTemplateParams.

An InstantiateVAppTemplateParams request body that incorporates one or more SourcedItem elements supports the following configuration changes:

Change the name, Description, and NeedsCustomization properties of the virtual machine.

Specify a storage profile for the virtual machine.

Specify a storage profile for any of the virtual machine's hard disks, overriding the virtual machine's default storage profile.

Increase the capacity of the virtual machine's SATA or SCSI disks.

Increase or decrease the size of the virtual machine's memory.

Increase or decrease the number of CPU cores per virtual socket.

Add or remove CPUs.

You can also modify any of these configuration settings after the vApp is deployed. See Configuring vApps and Virtual Machines.

Verify that you are logged in to the vCloud API as an administrator, Catalog Author, or vApp Author.

Review the current configuration of the vApp and its virtual machines. Configuration parameters in the VAppTemplate such as its NetworkConfigSection and LeaseSettingsSection affect all virtual machines in the vApp. Configuration parameters for individual virtual machines are defined in Vm elements in the VAppTemplate. A virtual machine's network connections are defined in its NetworkConnectionSection, and its hardware configuration is defined in its VirtualHardwareSection. To view the configuration of a virtual machine in a vApp template, you can retrieve the template and examine the VirtualHardwareSection of that Vm, or you can download the OVF descriptor of the vApp template, as shown in Download the OVF Descriptor of a vApp or vApp Template.

1

To change the name, Description, or NeedsCustomization properties of the virtual machine, add a VmGeneralParams element to the SourcedItem.

2

Examine the OVF descriptor of the template to determine the values that you can include in the VirtualHardwareSection of the SourcedItem element.

3

Include the SourcedItem element in an InstantiateVAppTemplateParams element.

4

Make a POST request to the action/instantiateVAppTemplate URL of the VDC.

Supply the InstantiateVAppTemplateParams element as the request body.

This InstantiateVAppTemplateParams request extends the request shown in Example: Instantiate a vApp Template to include a SourcedItem element that makes several configuration changes in the virtual machine referenced at https://vcloud.example.com/api/vAppTemplate/vm-4.

Changes the name and Description of the virtual machine, so that they are not the same as the name and Description in the template.

Sets the value of NeedsCustomization to true.

Adds a virtual CPU and changes the value of CoresPerSocket to 2. If you include a CoresPerSocket element, its value must be an integer multiple of the value of the existing rasd:VirtualQuantity of CPU items, or of the value you supply in NumberOfCpus. Example: Modify the CPU Configuration of a Virtual Machine shows the original CPU configuration, and how to make this change by reconfiguring the virtual machine in a deployed vApp.

Increases the capacity of the hard disk from 1GB to 10GB by including a Disk element that specifies a Size of 10240 for the disk that has a rasd:InstanceID value of 2000. The value you supply for Size is interpreted as megabytes. You can see the original disk configuration in Example: Retrieve the Hard Disks and Controllers in a Virtual Machine . Example: Modify the Hard Disk Configuration of a Virtual Machine shows how to make the same change by reconfiguring the virtual machine in a deployed vApp. If you include a Disk element, the value of its instanceId attribute must match the value in the rasd:InstanceID element of an existing Item that defines a virtual disk (RASD resource type 17). Disk capacity can be raised, but not lowered, for disks on SATA and SCSI controllers. The capacity of other disk types cannot be changed. Item elements that represent SATA disks have a vcloud:busType attribute with the value 20. Those that represent SCSI disks have a vcloud:busType attribute with the value 6.

With the exception of the changes specified in VmGeneralParams (name, Description, and NeedsCustomization), this example has the same effect as the example in Example: Modify Virtual Machine Hardware During vApp Template Instantiation.

Important

You cannot mix SourcedVmInstantiationParams and SourcedItem elements in a single InstantiateVAppTemplateParams request body.

Request:

POST https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate
Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateVAppTemplateParams
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="Linux FTP server"
   deploy="true"
   powerOn="true"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1">
   <Description>Example FTP Server</Description>
   <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111"/>
   <SourcedItem>
      <Source href="https://vcloud.example.com/api/vAppTemplate/vm-4"/>
      <VmGeneralParams>
         <Name>ftp1</Name>
         <Description>Primary FTP Server Instance</Description>
         <NeedsCustomization>true</NeedsCustomization>
      </VmGeneralParams>
      <InstantiationParams>
         <NetworkConfigSection>
            <ovf:Info>Configuration parameters for logical networks</ovf:Info>
            <NetworkConfig networkName="vAppNetwork">
               <Configuration>
                  <ParentNetwork href="https://vcloud.example.com/api/network/54"/>
                  <FenceMode>bridged</FenceMode>
               </Configuration>
            </NetworkConfig>
         </NetworkConfigSection>
         <LeaseSettingsSection
            type="application/vnd.vmware.vcloud.leaseSettingsSection+xml">
            <ovf:Info>Lease Settings</ovf:Info>
            <StorageLeaseInSeconds>172800</StorageLeaseInSeconds>
            <StorageLeaseExpiration>2013-11-01T08:00:22.001-07:00</StorageLeaseExpiration>
         </LeaseSettingsSection>
         <ovf:VirtualHardwareSection
            xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"
            xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
            xmlns:vmw="http://www.vmware.com/schema/ovf"
            xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
            xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
            ovf:transport=""
            vcloud:href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/"
            vcloud:type="application/vnd.vmware.vcloud.virtualHardwareSection+xml">
            <ovf:Info>Virtual hardware requirements</ovf:Info>
            <ovf:Item>
               <rasd:AddressOnParent>0</rasd:AddressOnParent>
               <rasd:Description>Hard disk</rasd:Description>
               <rasd:ElementName>Hard disk 1</rasd:ElementName>
               <rasd:HostResource
                  xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
                  vcloud:capacity="10240"
                  vcloud:busSubType="lsilogicsas"
                  vcloud:busType="6"></rasd:HostResource>
               <rasd:InstanceID>2000</rasd:InstanceID>
               <rasd:ResourceType>17</rasd:ResourceType>
            </ovf:Item>
            <ovf:Item>
               <rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits>
               <rasd:Description>Number of Virtual CPUs</rasd:Description>
               <rasd:ElementName>1 virtual CPU(s)</rasd:ElementName>
               <rasd:InstanceID>41</rasd:InstanceID>
               <rasd:Reservation>0</rasd:Reservation>
               <rasd:ResourceType>3</rasd:ResourceType>
               <rasd:VirtualQuantity>2</rasd:VirtualQuantity>
               <rasd:Weight>0</rasd:Weight>
               <vmw:CoresPerSocket>2</vmw:CoresPerSocket>
            </ovf:Item>
         </ovf:VirtualHardwareSection>
      </InstantiationParams>
      <StorageProfile href="https://vcloud.example.com/api/vdcStorageProfile/33">
      </StorageProfile>
   </SourcedItem>
   <AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>

The response is a sparsely populated VApp element, as shown in the response portion of Example: Deploying a vApp.