Composting vApp(s)

I was so tempted to write code here but I should point the readers to the community (link available in the resource section) where complete example is available. Never the less let me add the pointers here.

When we compose a vApp, we are creating a new vApp which can contain its child VM(s) from various sources. These sources can be VM from an existing template or a VM from existing vApp.  Simply put we are picking up assortment of VM that we like and making a copy of them to be part of the new vApp.
Let’s see step by step, how to go about it.
1.    First and foremost we need to create composition parameters by using ComposeVAppParams object.  We need to set basic information such as Name, Boolean indicating if we want to deploy it and so forth. We also need to set up the instantiation details as we did while instantiating template to vApp.  That basically involves setting up the vApp Network configuration.
2.    Composition parameters contain a list of ‘Source Items’. These source items are nothing but references to VM that need to be added to the composed vApp.

List<SourcedCompositionItemParamType> items =  composeVAppParamsType.getSourcedItem();

ReferenceType vappTemplateVMRef = new ReferenceType();

vappTemplateVMRef.setHref(vmHref);
vappTemplateVMRef.setName(“ChildVm1”);
vappTemplateItem.setSource(vappTemplateVMRef);
   
// Now add this VM reference to the Composition parameters’ item list
items.add(vappTemplateItem);
// More items (VM) can be added to this ‘items’ list

3.    Optionally set up networking for the all child VM(s) now.

One can chose to use the same VM and add it multiple times such that the composed vApp has  more than one such child VM.  It is necessary to use different name for the Reference used in the step 2 above.  We are mainly interested in the HREF that we set on the reference object.


The actual step of composing the vApp using SDK looks as simple as
Vapp vapp = vdc.composeVapp(createComposeParams(vappTemplateRef, vdc));

The actual work is creating the composing details
When recomposing the vApp if you are adding new VM(s) then the steps are exactly same as above where in actual work is creating RecomposeVAppParamsType. You need to add new SourcedComposition Item. If VM needs to be deleted from existing vApp then you need to populate the ‘Delete Item’ list.

// create the recompose vapp params type.

RecomposeVAppParamsType recomposeVAppParamsType = new RecomposeVAppParamsType();

recomposeVAppParamsType.setName("RecomposedVapp");
       

 // adding the vm item.
 List<SourcedCompositionItemParamType> newItems = recomposeVAppParamsType.getSourcedItem();
  newItems.add(vmItem);

How to create a new vApp

There are many ways one can create a vApp in vCloud, and they vary depending on where one starts. Here are some of the options. As promised we will use the SDK to illustrate the example(s).

• Create one form a template (POST .../api/v1.0/vdc/<vdc-id>/action/instantiateVAppTemplate)
• Start from OVF package.
• Assorted vApp:
• Compose new vApp from templates and/or existing vApp
  (POST .../api/v1.0/vdc/<vdc-id>/action/composeVAp)
• Recompose vApp to add/delete VM in it.
  POST .../api/v1.0/vApp/<vapp-id>/action/recomposeVApp (This is not really creating a new vApp so we will visit it next time).
• Clone from existing vApp POST .../api/v1.0/vdc/<vdc-id>/action/cloneVApp
• Importing from vSphere 

Let’s visit the above one by one:
1.    Start from OVF Package:
This is the most ground up operation one can think of for creating a vApp. You are basically loading the vApp from the OVF as a vApp Template in a catalog and then its matter of details for instantiating vApp from template as in #2. So let’s look at the first thing first: uploading OVF as vApp Template. The OVF file essentially describes how the vApp is configured using various ‘Sections’ and bundles with the  disk files of the virtual machine. Even before we upload this vApp description we need to create a ‘vApp Template’ object in the vCloud. The SDK provides a method on Vdc object ‘createVappTemplate’.

UploadVAppTemplateParamsType vappTemplParams = new
UploadVAppTemplateParamsType();

vappTemplParams.setDescription("New Template Description");
vappTemplParams.setName("NewVAppTemplate");

VappTemplate vappTemplate = vdc.createVappTemplate(vappTemplParams);

It goes without saying that this template needs to be later added to a Catalog. Once the object is created we upload the OVF descriptor using method on newly created vApp template ‘uploadOVFFile’.

File ovfFile = new File(ovfFileLocation);

FileInputStream ovfFileInputStream = new FileInputStream(ovfFile);

vappTemplate.uploadOVFFile(ovfFileInputStream, ovfFile.length());

 As a result of resolving the OVF descriptor, the Template object knows how many virtual machines are part of the vApp and how many disk every machine has. We are yet to upload the disk files so as a pre-requisite for that it creates a place holder link for those disk files and adds details to the vApp Template object. Make sure that you refresh the vApp Template object on the client side so as to get this newly available configuration data. Now you can upload the disk files to the cloud and take a coffee break.

// wait to make sure OVF descriptor is uploaded.
// Refresh the vApp Template object.
File vmdkFile = new File(vmdkFileLocation);
FileInputStream vmdkFileInputStream = new FileInputStream(vmdkFile);

vappTemplate.uploadFile(vmdkfileName, vmdkFileInputStream, vmdkFile.length());

 Once done go on to the next step of creating a vApp from template as follows. All this available in the sample provided as part of the vCloud SDK.