RCU API v2.1 Examples
The Rapid Cloning Utility (RCU) Application Programming Interface (API) was released with RCU version 2.1. The API is exposed using Simple Object Access Protocol (SOAP). This API can be thought of as a 'higher level' API which makes use of the NetApp Controller API (know as the Manage ONTAP SDK) and the VMware Virtual Center API (known as the VMware vSphere Web Services SDK). Neither additional API is required for an application or script to consume the RCU API.
The RCU API is designed to be leveraged with the VMware vSphere Web Services SDK to offload the intricacies of storage object cloning while cloning virtual machines. To this end, the managed object reference returned by the VMware vSphere Web Services SDK is used to identify components in the vCenter Inventory. You can view this information using the Managed Object Browser on the vCenter server.
The documentation for the RCU API is found in Appendix C of the Rapid Cloning Utility 2.1 Installation and Administration Guide. The purpose of this document is to provide some examples written in java and perl.
The rcuApiSamples.zip file contains both the perl and java samples. Also included in the java directory is an package called api. This package was generated using the wsimport tool which is included in Java 6. An example syntax for generating this package is in Appendix C of the 'Installation and Administration Guide'.
Java
The java examples leverage an class named RcuUtil.java. The purpose of this class is to bypass java security normally required for https. This should only be use in development and possibly test. There are steps outlined in Appendix C of the Rapid Cloning Utility 2.1 Installation and Administration Guide for configuring the java application to work with the self signed certificate used in the RCU service. Information here and the tool posted here may be helpful.
The following examples are provided. A brief description follows each.
CreateVmsWithDefaults.java
This example shows how to clone VMs in an existing datastore. The vm named javaDemo will be cloned 3 times. The new clone names will be curly, larry, and moe. The new vm named curly will be powered on after cloning, but the other two will not. The controller that provides this datastore is 10.61.167.51. The destination for these new clones is the datacenter named MFIT1.
CreateVmsInNewNFS.java
This example shows how to clone a VM into a new NFS based datastore. The vm named javaDemo will be cloned 3 times. The new clone names will be curly, larry, and moe. The controller that the new datastore should be created on is 10.61.167.51. The new NFS datastore will be named apiDemo, will be 200GB in size, will be thin provisioned, and will grow in increments of 10GB as needed to a maximum size of 400GB. The destination for these new clones is the datacenter named MFIT2.
CreateVmsInNewNFSDatastores.java
This example shows how to clone a VM into new NFS based datastores. The vm named javaDemo will be cloned 6 times. The new clone names will be fred, daphne, velma, shaggy, scooby, and scrappy. The controller that the new datastores should be created on is 10.61.167.51. The gold volume will be named apiDemo and created in the aggregate named aggr1. The new NFS datastores (flexclones of apiDemo) will be named mysteryMachine, spookyHouse, and spookyMine. Each will be 200GB in size, will be thin provisioned, and will grow in increments of 10GB as needed to a maximum size of 400GB. The destination for these new clones is the datacenter named MFIT2. Please note the number of vm clones must be evenly divisible by the number of datastores. In this example we've requested 6 vms and 3 datastores. This will result in 2 vms per datastore.
CreateVmsInNewVMFSDatastores.java
This example shows how to clone a VM into new VMFS based datastores. The vm named javaDemo will be cloned 6 times. The new clone names will be fred, daphne, velma, shaggy, scooby, and scrappy. The controller that the new datastores should be created on is 10.61.167.51. The new luns will be created in the existing volume named vmLuns. The new VMFS datastores (luns) will be named mysteryMachine, spookyHouse, and spookyMine. Each will be 200GB in size, thin provisioned and accessed via ISCSI. The destination for these new clones is the datacenter named MFIT2. Please note the number of vm clones must be evenly divisible by the number of datastores. In this example we've requested 6 vms and 3 datastores. This will result in 2 vms per datastore.
Perl
This perl example leverages SOAP::Lite. We used version 0.710.08 to test this example. George Costea pointed out that there is an issue with this module, specific to RHEL. More information can be found here. We have also had a report that some versions of SOAP::Lite will pass "true" in the SOAP message when the String "false" is used. To correct this, use 0 (zero) to indicate false. While we chose to use SOAP::Lite for this example, it is not required. There are other perl modules that provide SOAP functionality, please feel free to use whatever you are most comfortable with.
The following example is provided. A brief description follows.
createClones.pl
This example shows how to clone VM into existing datastore(s). A special thanks to David La Motta for providing the majority of this example. The vm named perlDemo will be cloned 3 times. The new clone names will be curly, larry, and moe. The new vm named curly will be powered on after cloning, but the other two will not. The controller that provides this datastore is 10.61.167.51. The destination for these new clones is the datacenter named MFIT1.
Other Perl Examples
Applying a Custom Spec and Separating OS and SWAP disks with the Perl API example