You specify configuration details for vApps and the virtual machines they contain in ovf:SectionType elements contained in a VApp or Vm element. You can include most of these sections in the InstantiationParams that you supply when you instantiate a vApp template. You can also retrieve, modify, and update these sections to reconfigure a deployed vApp.

You establish the initial configuration of a vApp in the OVF package on which its source template is based. You cannot modify most sections of the template, but you can update the configuration during the following operations:

When you create a vApp by making an instantiateVAppTemplate request, you can update its configuration by including modified sections in the request's InstantiationParams element.

When you compose or recompose a vApp, you can update its configuration by including modified sections in the request's InstantiationParams element.

When you update any of the modifiable sections in a deployed vApp or the virtual machines that it contains.

You can capture the reconfigured vApp to create a vApp template that preserves your modifications. See Capturing and Importing vApps.

You can update the following sections of a vApp template.

CustomizationSection

You can use a PUT request to update this section, which contains a Boolean value, CustomizeOnInstantiate, that specifies whether guest customization should be run during instantiation. You cannot modify this element if the vApp template has been added to a catalog.

Name and description

You can use a PUT request to update the value of the template's name attribute or the contents of its Description element.

Owner

You can use a PUT request to update the value of the template's Owner element. See View or Change the Owner of an Object.

ProductSection elements

You can retrieve or update the template's ProductSection elements, which provide a way to pass runtime information to the virtual machines defined in the template. See Retrieve or Modify ProductSection Elements.

Except for the Owner element, all updates to a vApp template propagate to the vApp during instantiation. The owner of the vApp is set to the identity of the user who instantiates the template.

You can include the following sections in the InstantiationParams associated with an instantiateVAppTemplate, composeVApp, or recomposeVApp request. You can also modify them in a deployed vApp.

LeaseSettingsSection

Defines the terms of storage and deployment leases for the vApp. If this section is omitted, the vApp inherits the default lease settings of the containing organization.

NetworkConfigSection

Defines the properties of the vApp network and specifies how it is connected to a network in the vDC. Unless you intend to create a vApp that has no connection to any network, you must include this section in the InstantiationParams element of an instantiateVappTemplate request.

StartupSection

Defines the order in which the virtual machines in the vApp start up and shut down. If this section is omitted, the startup and shutdown order of virtual machines in the vApp is indeterminate.

You can configure a virtual machine by updating any of the following sections of a Vm element:

VirtualHardwareSection

Contains a description of the virtual hardware supported by a virtual machine. You can reconfigure individual items in this section, or reconfigure groups of related items such as hard disks or network interface cards.

OperatingSystemSection

Specifies the guest operating system installed on the virtual machine.

NetworkConnectionSection

Specifies how the virtual NIC devices on the virtual machine are connected to the vApp network.

GuestCustomizationSection

Contains guest customization parameters for the virtual machine.

There are several ways to update these sections:

You can include any or all of the sections in the InstantiationParams for a Vm.

You can include any or all of the sections in a reconfigureVm request.

You can use the workflow in Reconfiguration Workflow to update individual section or groups of related section.

The workflow for reconfiguring a vApp or virtual machine is the same regardless of the section you are modifying.

1

Retrieve the vApp or Vm and examine the response to find the section that you want to modify.

2

Retrieve the section by making a GET request to the URL in the section’s href attribute value.

3

Modify the section as needed.

4

Update the section by making a PUT request to the section’s edit link, a Link element in the section where rel="edit", and supplying the modified section in the request body.

Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only. See the schema reference for details.

Note

You cannot make configuration changes to a vApp if it is in maintenance mode. A system administrator can put a vApp into maintenance mode to prevent metadata changes during administrative operations such as backup, restore, and upgrade. See Summary of vSphere Platform Extension Requests.