vCloud Director v9 Multi-site

Since vCloud Director v9 was released last week (and previously as part of the closed beta), one of the new features I’m most excited about is support for multi-site deployments. This allows vCloud Director environments for the first time to properly span federated sites (e.g. a tenant who has resources in multiple datacenter locations for resiliency/redundancy can now manage these in the same place).

Configuring multi-site support in vCloud Director v9 is a 2-part process:

1) The service provider has to configure federation between their vCloud Director instances.
2) The tenant has to associate each of their Organizations in each vCloud Director instance.

This post will attempt to explain and show both processes, and there’s even a bonus of a PowerShell script I’ve written to help other service providers configure their site pairings. To help demonstrate the processes involved, I’ve built a test lab environment consisting of 4 separate vCloud Director instances (‘Auckland’, ‘Wellington’, ‘Christchurch’ and ‘Dunedin’ sites). Each of these has it’s own vCloud Director, vCenter, NSX and ESXi hosts. I’ve also created a tenant organization (‘Tenant X’) in all 4 instances and created and assigned a VDC to Tenant X in each location. Finally, I’ve federated Tenant X’s vCloud users with a directory service (Microsoft AD FS in this case) so that the same identity provider is available to all 4 vCloud instances.

If you’re not a service provider and just need to configure Organization pairing you’re probably safe to skip this section and proceed straight to the 2nd part of this post.

Part 1 – Service Provider Site Pairing

The basic process for a service provider to pair sites is:

– Check (and configure if necessary) the vCloud site name in each location. Note by default in the initial vCloud Director 9 release this is simply a GUID string so you’ll probably want to change it to something more meaningful.
– Download from each site the site association document (from /api/site/associations/localAssociationData)
– Upload this site association document to each other site that you want to pair with (to /api/site/associations)

In a scenario with only 2 sites you need to perform this process twice (once in each direction), but for our example with 4 sites we need to do this a total of 12 times to pair every site with every other site.

Being a bit of a pain to do manually against the REST API interface I ran true to form and wrote a PowerShell module to simplify the process of both administering the site names and also pairing sites together. The module is available on my github repository at The script uses my Invoke-vCloud module, so you’ll need that installed for it to run.

Once you’ve downloaded the vCDSitePair.psm1 file from github you can add it to your PowerShell session using ‘Import-Module ‘

There are a total of 4 functions provided by the module, and they are documented on the github repository but basically:

Get-vCloudSiteName Allows a service provider to check/confirm the ‘Site Name’ assigned to a vCloud Director instance.
Set-vCloudSiteName Allows a service provider to set/update the ‘Site Name’ assigned to a vCloud Director instance.
Get-vCloudSiteAssociations Shows the existing associations (if any) from a vCloud Director instance.
Invoke-vCDPairSites Performs the 2-way exchange of localAssociationData documents to pair two vCloud Director instances.

So to confirm/set the names of our ‘Auckland’ (akl.mycloud.local) and ‘Christchurch’ (chc.mycloud.local) sites we can use Get-vCloudSiteName and Set-vCloudSiteName:

Now we have set the site names, we can check if they are already associated:


Ok, so they’re not already associated, so we can run Invoke-vCDPairSites without the ‘WhatIf $false’ to see what would happen:

That all looks good so now we can attempt the action pairing operation:

And confirm the associations using Get-vCloudSiteAssociation again:

(I’ve cut out the certificate dumps for brevity).

So now that our Auckland and Christchurch sites are paired we can move on with associating the Organization (‘Tenant X’) between these sites. I’ve also been through and associated all of the other sites to each other, so by this stage ‘Auckland’ is associated to ‘Wellington’,’Christchurch’ and ‘Dunedin’ etc.

Part 2 – Organization Site Pairing

Originally I was intending to write PowerShell functions for this too, and while this is certainly possible, VMware have been nice to us and created the capability in the new vCloud Director tenant UI. Logging in as a user with ‘Organizational Administrator’ access shows an ‘Administration’ tab:

Selecting the ‘Administration’ tab reveals the site pairing options:

When we select ‘Export Local Association Data’ a file is downloaded (named ‘Download’ weirdly enough) and this file can be uploaded to the ‘partner’ site using the other ‘Create New Organization Association’ button. Once completed, the association is shown in the panel – here is the Auckland site for ‘Tenant X’ once the Christchurch Local Association Data has been uploaded to it:

You can click on this panel to see the association details and even remove a site association if no longer required:

Here’s the view of the ‘Christchurch’ environment once I’ve paired the ‘other’ 3 sites to it for this Organization:

Once we’ve added all our associations (and logged out and back in) we can see the new multi-site drop-down menu item which allows us to select from any of our datacenter locations:

And selecting one (‘Auckland’ in this case) takes us to the Auckland resource view:

All in all, a little bit of a convoluted process, but at least it should only need to be done once and can then be left alone. Very excited to see what VMware do with this functionality in future – can definitely see a time when all of an Organization’s VMs are displayed / summarised in a single view regardless of which vCloud instance supports them.

I have several more thoughts generally on vCloud Director v9 which I’ll put into a separate post when I have time, but wanted to get this published for anyone else playing around with the new multi-site features.

As always, comments and feedback appreciated.


Tagged , , , , , . Bookmark the permalink.

6 Responses to vCloud Director v9 Multi-site

  1. Massive post! Have shared. Should drop this on the VMware advocacy channel Jon so it get picked up and shared by the masses.

  2. Marco says:

    Very good post. Thank you.

  3. Marcelo San Martin says:

    (previous comment.. email address was wrong)

    Hi. Can you help us with the following.

    We are getting the following error when we try a “Set-vCloudSiteName” (Get-vCloudSiteName is working OK)

    Invoke-vCloud : No existing session found and no vCloudToken specified, cannot authenticate, exiting.
    At C:\Users\Administrator\Documents\WindowsPowerShell\Modules\vCDSitePair-master\vCDSitePair.psm1:67 char:17
    + … $response = Invoke-vCloud -URI $editURI.href -ContentType ‘applicatio …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Invoke-vCloud

    We are using vCloud Director 9.0.1

    • Jon Waite says:

      Sorry for the delay in replying, it sounds like you’ve hit the same issue I had recently when testing – the part of the code that gets your session ID matches the domain used to connect with Connect-CIServer, if these mismatch then it won’t work. The easiest fix is to make sure that you use the exact same cloud endpoint as is defined in your installation.

      e.g. if you have a vCloud installation with ‘mycloud.service.provider’ as the public URI, ‘cell01.mydomain.local’ as the local DNS for this cloud and an IP address of assigned externally and internally, even though all of these will work with ‘Connect-CIServer -Server xxx’ make sure you use whatever is specified in your Public URLs when you connect from PowerShell (e.g. Connect-CIServer -Server ‘mycloud.service.provider’).

      Hope that helps, let me know if that fixes your issue.

  4. Jonathan says:

    Thank you for the post as it was informative. I was woundering if you have seen an issue where there are two sites, and after associating each site with one another, neither one ever change from ASYMMETRIC to Active or know where the logs for this would be located.

  5. Prem says:

    I am struggling to find any example of how to delete an existing site association. Would you be able to provide API example and maybe at some point extend your module with this feature? Thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *