Category Archives: Technical How To

vCloud API sample

This sample code shows step–by-step  how to use the vCloud API to deploy a new vApp from a template.  Our template vApp in this example contains a single linux (CentOS) virtual machine.

We are going to be making calls to the API directly using ‘curl’. Please note that VMware provide language specific wrappers for the API which simplify the process of using it. Wrappers are available for Java, PHP and .net.

This example is working with the StratoGen UK cloud. The organization name is called ‘test’ and I have a user called ‘user1’ with a password of ‘password’.

Let’s get started…

Step 1

The first thing we need to do is login and get our ‘authentication token’. The username and password are passed in the format user@organization:password.

curl -i -k -H "Accept:application/*+xml;version=5.1" -u "user1@test:password" -X POST

1 login

The authentication token is found in the first response header. We need to use this authentication token as a header in all our subsequent API calls.

Step 2

The response body contains links that provide access to our org. We are going to use the link provided as a http GET as follows:

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET

2 get org

The response provides links to various attributes and actions to do with the org.

Step 3

The first thing we will need to do is find the ID of our template vapp. This is achieved by locating the catalog first and then the vApp template within it. We need the ID of the template as it is used when we deploy our new vApp later in this guide.

Our catalog is called “testcatalog” so we use the appropriate link from the previous step.

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET

3 get catalog

The output lists the items within the catalog.

Step 4

The catalog item that we are going to use in this example is “centostemplate” listed as

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET

3b get vapp template

The vApp template we are going to use is thus

Make a note of the reference as we will use it in the following steps.

Step 5

We are now ready to deploy a new vApp based on our template. The action to deploy a vApp from a template can be found in the virtual datacenter (vDC). The link to the vDC can be found in the response to our ORG query in Step 2.

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET

4 get vdc

The response lists various actions that are available to us. The one we will be using is called instantiateVAppTemplate.

Step 6

We need to pass some parameters regarding the vApp we want to create. In the API these are known as InstantiateVAppTemplateParams.

 name="new one"
 <Description>New vApp</Description>
 href="" />

The important bit here is the Source field which was found in step 4. The name and Description fields should be what you wish to call your new vApp. I have set deploy and powerOn to “true” which means the vApp will be powered on as soon as it is deployed.

I have created a small text file called “instantiate-params” so that we can pass this information using curl.

5 instant params


Step 7

We are now ready to deploy our new vApp. We use the POST method to call the API and pass our “instantiate-params” file using the –d option. Note that we include a Content-Type header.

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw="  -H "Content-Type:application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" -X POST -d @instantiate-params

6 deploy vapp

Step 8

The response shows us that the vApp is being deployed. We can use the <task> link to check when the process has completed but in the case of the StratoGen cloud this is usually just a couple of seconds.

If we log on to vCloud Director at this point we can see the vApp being created.

portal creating

The response from the API call also passes us a link to the newly created vApp. Using this we can get information such as IPs of VM:

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET

There is a lot of information in this response. A snippet showing the IP address of the new VM is shown here:

7 response

A final look at vCloud Director shows our new vApp has been deployed and is running.

portal deployed

At this stage we can log on to the virtual machine and start using it.

vCloud Director Edge Gateway

Edge Gateway 5.1 in vCloud Director 5.1


 Part 1: Networks, IP assignment, NAT and Firewall

The Edge Gateway feature in Vcloud Director 5.1 is the evolution of the Routed Organisation Network in Vcloud Director 1.5. The Edge Gateway is implemented using vCloud Networking and Security (formerly vShield) and is fully integrated into vCloud Director. I will be looking specifically at the vCloud implementation of the Edge Gateway and how to configure the various features for your virtual Data Centre. Features include:

DHCP server*
Network Address Translation (NAT)*
Load Balancer**
Static Routes

*enhanced from vCD 1.5
** New feature in vCD 5.1

Notable enhancements from the vCD 1.5 implementation include the ability to have more than 2 interfaces on an Edge Gateway (up to 10, internal or external), a higher specified ‘full configuration’ and an HA configuration.

In this first post I will be looking at the types of networks available in vCloud Director, adding networks, assigning IP addresses to vApps and configuring NAT and firewall rules. In part 2 I will look at configuring the Load Balancer feature and VPN configuration.

Deployment of an Edge Gateway

As a vCloud user, it is necessary to get your vCloud Provider (such as StratoGen) to deploy the Edge Gateway into your organisation. You will need to provide some information such as how many external IP addresses you will require, what your internal network address ranges are and whether you will need the compact edition or the full edition.
The compact edition has 1 x vCPU and 256MB RAM and the Full edition has 2 x vCPU and 1GB RAM.
Bear in mind your provider may levy an additional charge for the increased resources used by the full edition.

External Networks, Org VDC Networks and vApp networks

Prior to deploying an Edge Gateway it is useful to have a bit of background on how networks are presented in vCloud Director. There are three main types: External, Organisation and vApp.

External Networks
These are configured in vCloud Director by the service provider. In essence they present a port group from the underlying vShere infrastructure to vCloud Director. The service provider configures the IP range or ranges available on the port group in vCloud Director. The IP range may be a shared range that multiple customers can utilise or the service provider may present a dedicated range for a specific customer.
The Edge gateway will need to connect to one or more external networks. Your service provider will provide details on what options are available and the number of public IPs you are entitled to.

Org VDC networks
Org VDC networks are configured in your virtual data centre (VDC). As a customer you can create two types of Org VDC network: isolated or routed.
Isolated networks are effectively internal networks that can only be accessed by vApps in your VDC. They can be shared between VDCs in the same organisation but cannot be used to access external networks. You still have to define a default gateway IP for an isolated network, and it still deploys an appliance, but the only configurable service on an isolated network is DHCP.
Routed networks are internal networks that can be shared between VDCs in the same organisation, but the major difference is that they also connect to an Edge Gateway’s internal interface. vApps connected to a routed network use the Edge Gateway’s internal IP address as their default gateway.

The service provider is also able to add a third type of network to your VDC. It is a direct connection to an External network (as described above). This may be to give you access to either a shared or dedicated IP address pool. For example the provider may present an Org VDC Network that connects directly to a shared public IP range configured as an External network in vCloud Director.

vApp Networks
vApp networks are configured within the vApp rather than at the Org VDC level. They can connect directly to an Org VDC network or via a routed connection to an Org VDC network. If a routed connection is created a compact Edge Gateway appliance is deployed for the vApp, which has a reduced feature set (DHCP, Static routing, NAT and Firewall) than an Organisation level Edge Gateway. We will cover vApp networks in another post.

Once you have decided on your network topology you can ask your service provider to deploy the Edge Gateway for you. For this article I will use a simple topology with 2 Internal networks and access to a single external network.


So now my provider has deployed an Edge Gateway, they also need to sub-allocate IP ranges to the gateway for me to use for my services. These are the public IP addresses I will use for NAT rules and VPN connections. The Gateway will have at least 1 IP address already on the External Network, and that IP can be allocated for use in NAT rules or VPN connections. My provider has also allocated 2 extra public IP addresses for me to use. These will be allocated to me and cannot be used by any other device on the External network. In my case the provider has attached my Edge Gateway to a shared IP range so other customers may have IPs on the same Public IP space. The other option would have been to request a dedicated subnet.

I am going to configure my network as follows:

vApp1 has a single Windows server which will offer FTP services publicly. I want to be able to access it via VPN from my other vCloud platform (details in Part 2!). I will use DHCP to allocate the Server an IP address.
vApp2 has 2 CentOS servers running apache. I want to use the load balancer feature to allow http access publicly (details in Part 2!) and also to allow SSH administration from the Internet. I will use IP pool address assignment for this vApp.

Configuring the Org VDC Networks

To create an Org VDC Network go to the Administration tab in your vCloud Director Organisation and choose the VDC you wish to create the network in. Click on the Org VDC Networks tab then the plus sign:


I want to create a routed network so I’ve selected that option and also selected my Edge Gateway:


Click next and you can then define the internal network. For my 2 internal network I have set the following settings:

For the Windows FTP server network:


For the CentOS apache servers network:


The DNS servers could be DNS servers provided by your vCloud service provider, public (open) DNS servers, or servers internal to your VDC – It will depend on your deployment. For testing I used StratoGen’s DNS servers.

When the Org VDC networks have finished deploying (in the background this means configuring one of the unused NICs on the Edge Gateway and configuring a new port-group in vSphere) they will appear in the OrgVDC Networks pane:


You can also see that the Edge Gateway has 3 used NICs, 1 External Network and 2 Organisation VDC Networks confiured:


Once both Org VDC networks have been created they can be made avilable to any vApps deployed in the VDC. In the vApp go to the Networking tab and lick the plus sign. We want to add an Organisation VDC network:


Select the Org VDC network you want to add to the vApp:

Now the Virtual machines can be attached to the networks. For the Windows VM I am using DHCP so will configure the NIC on the VM as follows:


For the CentOS servers I am going to use IP Pool assignment. This is a vCloud Director feature that is similar to DHCP but has few important differences. When we created the Org VDC network we specified a range of IPs for our pool. You either assign IP addresses automatically as per the screenshot or specify addresses manually.


Once an address has been assigned it will be unavailable for other VMs on the same network. There are a couple of prerequisites for IP Pool address assignments: Guest Customization must be enabled which in turn requires that VMware tools are installed on the Virtual Machine. If you are running a Guest OS that doesn’t support VMware tools then consider using DHCP for automatic address assignment. The assigned IP address will be applied to the VM when it is powered on. You can check assigned IPs by right clicking on the Org VDC Network and choosing IP Allocation:



Configuring DHCP

We want to assign a DHCP address to our Windows server so we need to configure this first on our edge gateway. Right click on the edge Gateway and choose Edge Gateway Services. The DHCP tab is the leftmost tab and appears first. Currently there is no configuration there as you can see:


Click on add and enter an interface to apply the DHCP scope on – we want it on our WindowsFTPNet interface. I’ve chosen a range that doesn’t overlap with the IP Pool configured on the WindowsFTPNet Org VDC network. I’ve also decided to keep the lease times at the default.


Once that’s done click OK then tick the Enable box.


Click OK and the Edge Gateway will initialise the DHCP server. I’m now going to power on my Windows vApp. Once this has powered on we can see that the network adapter has picked up the first IP in the DHCP scope. It has also picked up the correct default gateway and the DNS servers (trust me on that one!) I configured on my Org VDC network.


So DHCP is working correctly but we don’t have Internet access as yet as we haven’t defined any NAT rules or firewall rules. I’m going to keep things simple by allowing outbound access to the Internet from all my VMs, but you may well want to be more stringent in your security configuration.

Before adding NAT rules I’m going to make sure my CentOS VMs have also been assigned the correct IP configuration. As these VMs were deployed from my provider’s catalog, they were both preinstalled with VMware tools and Guest customization was enabled already. If you were deploying a VM from scratch you would need to install these manually which you can do from the vCloud Director interface. The installation is automatic in Windows, but for Linux VMs it only mounts the VMware tools installer – you must complete the installation manually from the command line. You will need Perl installed, and for CentOS/RedHat Linux once the Installer is mounted run the following:

1. mkdir /cdrom
2. mount /dev/cdrom /cdrom
3. cd /tmp
4. tar -xvf /cdrom/VMwareTools (tab to auto-complete)
5. cd vmware (tab to auto-complete)
6.  ./
7.  umount /cdrom

Looking at the vCloud Director Interface it looks like it has assigned IPs successfully to the VMs:


If we check one of the VMs from the console we can see this is the case by running ifconfig:


So all our VMs have IPs assigned correctly in the networks they are attached to. Next we want to give them all the ability to access the Internet. This means configuring two further parts of the Edge Gateway: NAT rules and Firewall rules.

Configuring NAT and Firewall rules

In vCloud Director 5.1 you have more granular control over the NAT configuration in the Edge Gateway. Specifically you can configure Source NAT (SNAT) rules, which control traffic leaving the Edge Gateway’s external interface(s), and Destination NAT (DNAT) rules, which control traffic arriving at the Edge Gateway’s external interface(s).

Adding SNAT rules

To allow our VMs to access the outside world we are going to have to add a NAT rule for each internal Org VDC network. This will translate internal private IP addresses to a public address or addresses. For outbound access there’s no particular reason why you can’t use the same external IP address for all your internal networks. Depending on your configuration you may want to use a public IP for each internal network or even for individual VMs on that network. I will be using a single IP for all networks. Currently we have no NAT rules configured:


To create the SNAT rule we go to the NAT tab in Edge Gateway Services and click add. The SNAT rule is to be applied on the external interface that we will be using. I only have one configured but if you have multiple external networks you would apply the rule on the interface you want the traffic to egress from. The original (Internal) source IP/range is the Internal Org VDC range and the Translated (External) source IP/Range is the public IP or Ip range on the external interface you want your internal traffic to appear as on the Internet. Make sure the enabled box is ticked!


Click OK and the rule will be added to the NAT rule table. As you can see I have added an additional rule for the CentOsOrgnetwork as well applied on the external interface and using the same public IP.


There is one thing preventing the VMs from accessing the outside world now – The Firewall!

Configuring the Firewall

By default the Edge Gateway denies all traffic and this is how you should always configure a production firewall. For testing purposes it does allow you to set the default action to allow, but please remember to change this before putting it into production!

The Firewall on the Edge Gateway offers granular options for allowing access to services on your vCloud infrastructure. We want to allow our internal Org VDC networks access to the Internet, so we will add a rule for each Org VDC network.
In Edge Gateway services go to Firewall and click add. First give the rule a descriptive name. The source will be the internal network range. Source ports are set to any as we want all traffic to be allowed outbound. The destination is set to external – you could set this to any but external is more specific as we have multiple internal networks. Destination port and protocol are both set to any to allow my VMs full outbound access. Make sure the enabled box is ticked, then click OK.

In a production environment and depending on what services you are running you will most probably want to be a lot stricter with your outbound traffic.
Once we have clicked OK and the Edge Gateway has finished updating we can see our Windows box can get to the outside world.


As you can see from the screenshot below I have added another similar rule for the CentOS network.


So all our VMs can access the Internet, but if we want to publish services on our VMs that can be accessed from the Internet we will need to add some extra rules. We need Destination NAT (DNAT) rules to forward traffic from our assigned Public IPs to our internal networks and also firewall rules to allow the traffic to pass.

First of all I want to allow Remote Desktop access to my windows VM and SSH access to my CentOS VMS.

Adding DNAT rules

As with SNAT rules, DNAT rules are applied on the external interface you are using for the NAT translation. We only have one external interface so that makes our choice pretty easy. I am going to add a rule that forwards traffic destined for tcp port 3389 (Remote Desktop Protocol) on the public IP address to port 3389 on the private IP address of the Windows server.


Click OK. We now need to add a firewall rule to allow the traffic that has been forwarded to tcp port 3389 (please note the destination is the public IP – not the prviate IP).


In a production environment you would probably lock the source IP down to your location. Once this rule has been applied I can use RDP to manage my Windows server.
It’s important to note that in the latest version of vCloud Director Firewall rules use match on original addresses i.e. the public IP that you specified in the corresponding DNAT rule rather than the internal address.
As you can see from the following screenshot I have added DNAT rules for the CentOS servers to forward SSH traffic. For the second server I have changed the original port – this allows me to manage both servers on a single IP address.


I’ve also added the necessary firewall rules to the edge Gateway:


It’s important to note that firewall rules are applied in order (top to bottom), and if you need to alter that order you can do this easily by dragging and dropping the individual rules to where you want them in the list.

So now we have our 2 vApps accessible from the Internet for management purposes, and they are also able to access the outside world. In the next part of this blog I will look at setting up the Edge Gateway load balancer, and configuring VPNs as well as the accompanying firewall configuration.


vCenter Server Disconnecting From vCloud Director

Following on from my post on vCloud Director constantly syncing inventory I wanted to address a second point that could cause the underlying connection issue.

In the current revision of vCloud Director (5.1 and 5.1.1) there is an issue that may present itself as vCD disconnecting from vCenter at random times coupled with connection alerts from vCloud Director such as the email alert shown below.

vCloud Director is trying to reconnect to the vCenter Server Server ““.
When vCloud Director reconnects, it will send another email alert.

Further information of the error can be seen in the log /opt/vmware/vcloud-director/logs/vcloud-container-info.log.
Look for the following error.  ORA-01013: user requested cancel of current operation.
You can do this as follows.
# less /opt/vmware/vcloud-director/logs/vcloud-container-info.log
Then press / and type in user requested cancel of current operation to go to the location in the log where this entry is recorded.

As detailed in my previous post you can change the connection time to get around it to allow vCD time to reconnect to the vCenter Server. However there is another work around available that involves modifying the vCloud Director SQL database to remove some null entries that keep on creeping up in value and trigger this disconnect in the first place.

To do this I suggest you stop your vCloud Director cells first and make sure to backup the SQL server database. These instructions are for Oracle.

    1. Quiesce the services of the cells using the cell-management-tool and then stop the services with service vmware-vcd stop as described here.
    2. Backup the Oracle server.
    3. Open an SSH connection to the Oracle server and type sqlplus then provide the vcloud username and password.  (Hint username is vcloud)
    4. Run the following commands at the SQL> prompt.

SQL> select count(*) from task_inv where (status = 2 OR status = 3) AND completion_date is null;

This will return a numerical value, probably in the tens or hundreds of thousands. What we need to do is to run a series of commands to reduce this number down. It is this number that is causing vCloud Director to time out during the synchronization process.
Run these commands to fix this.

A. Get list of all vc_ids in the setup.
SQL> select distinct vc_id from task_inv;

B. For each vCenter in the setup.
1. Get max managed object value for that vCenter. That is the vc_id obtained from the above query.
SQL> select substr(moref, 6) from (select * from task_inv where vc_id = vc_id order by to_number(substr(moref, 6)) desc) where rownum = 1;

This will give result_1. Next we need to do some basic maths. We will keep ‘top’ 1000 entries per VC and will delete rest of them.

2. result_1 minus 1000 = result_2

3. Using the above result_2, run the following.

SQL> delete from task_inv where (status = 2 OR status = 3) AND completion_date is null AND vc_id = vc_id AND to_number(substr(moref, 6)) < result_2;

4. Run a commit; command.

5. Finally run the original query to see if the number has gone down.
SQL> select count(*) from task_inv where (status = 2 OR status = 3) AND completion_date is null;

Don’t forget to restart the cell services on vCD.  service vmware-vmd start and tail the cell.log to watch the progress of restarting the cell service. /opt/vmware/vcloud director/logs/cell.log -f

It will continue to creep up until VMware fix this in an update currently due as release version 5.1.2 at the end of April 2013.