You establish the initial configuration of a vApp and its virtual machines when you create it. After a vApp has been created by instantiation, cloning, composition, or recomposition, you can make further changes to its configuration using PUT requests that update modifiable elements of vApp and virtual machine objects.

Nearly all of the properties that you can specify when you create a vApp using any of the requests listed in Instantiation Parameters can be modified using a common reconfiguration workflow. Modifiable elements include a Link element where rel="edit". See Retrieve the Configuration Links for a vApp and Retrieve the Configuration Links for a Virtual Machine.

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.

Reconfiguration Workflow

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.
  5. To preserve these modification, you can capture the reconfigured vApp to create a new vApp template. See Capture a vApp as a Template.

Request bodies must contain all required elements and attributes, even if you are not changing their values. Because optional elements and attributes typically revert to default values if they are omitted or empty, it is a best practice to include optional elements in request bodies that modify existing objects. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes are read-only and cannot be modified. 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.

For a full list of the VMware Cloud Director API user operations, see the VMware Cloud API Schema Reference at https://code.vmware.com.