Instantiation parameters for a vApp template can modify the virtual hardware configuration, including network connections, of the virtual machines defined in the template.

An InstantiateVAppTemplateParams request body that incorporates one or more SourcedItem elements supports a number of changes to the configuration, including the virtual hardware configuration, of virtual machines in the template. For example:
  • 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.
  • Specify how the NICs in the virtual machine connect to vApp networks defined in the NetworkConfigSection of the vApp.
  • Specify virtual machine capabilities.
  • 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.
  • Assign a VDC compute policy.
You can also modify any of these configuration settings after the vApp is deployed. See Reconfiguring vApps and Virtual Machines.

Before you create or update the virtual hardware configuration of a VM, retrieve the list of virtual hardware versions supported by the organization VDC where the VM will be deployed. See Retrieve a List of Supported Virtual Hardware Versions and Guest Operating Systems.

Prerequisites

  • This operation requires the rights included in the predefined vApp Author role or an equivalent set of rights.Verify that you are logged in to the vCloud Air Compute Service as an End User.

  • 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 an OVF Descriptor or OVA File.

Procedure

  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.

Example: Modify Virtual Machine Hardware During vApp Template Instantiation

This InstantiateVAppTemplateParams request extends the request shown in Instantiate a vApp Template and Modify Virtual Machine Name, Description, and Storage Profile to include a SourcedItem element that makes several configuration changes in the virtual machine referenced at https://vcloud.example.com/api/vAppTemplate/vm-4.

  • 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. 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 Retrieve the Hard Disks and Controllers in a Virtual Machine. 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 increased, but not decreased, 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.
  • Assigns the VDC compute policy policy_vmGroup3_on_cluster_2.
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>
   <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>2014-04-25T08:08:16.438-07:00</StorageLeaseExpiration>
      </LeaseSettingsSection>
   </InstantiationParams>
   <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>
         <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">
      <VdcComputePolicy
         href="https://vcloud.example.com/cloudapi/vdcComputePolicies/urn:vcloud:vdcComputePolicy:74"
         id="urn:vcloud:vdcComputePolicy:74"
         name="policy_vmGroup3_on_cluster_2"
         type="application/vnd.vmware.vcloud.vdcComputePolicyType+xml"/>
      </StorageProfile>
   </SourcedItem>
   <AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>

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