SSO for vCloud Availability Portal UI

This is a quick followup on my yesterday’s blog post that discussed how to customize vCloud Director UI with additional links. vCloud Availability has separate Portal UI where the users can monitor status of their replications and optionally trigger failover operations. Wouldn’t it be nice if the link from vCloud Director UI would automatically sign in the user into the vCloud Availability Portal UI?

Quick chat with the engineers showed that indeed it is possible by leveraging the {vcdSession} variable that provides the vCloud Director session token. The URL provided in the link then must look like this:

https://<vCloud_Availability_Portal_UI_FQDN >:8443/login?token={vcdSession}

In my case the CMT command for the whole link would look like this:

./cell-management-tool manage-config -n ui.tenant.customOrgLinks -v "
# vCloud Availability
[Monitor Replications]({vcdSession})"

And this is the end result:

Click on the Monitor Replications link above (red box) opens vCloud Availability Portal screen with the tenant signed, in the next browser tab (below).

How to Customize vCloud Director UI

Service providers who are offering additional services beyond vanilla vCloud Director IaaS were asking how to add links to them in the existing (Flex) vCloud Director UI.

vCloud Director 8.20 provides very simple way to extend the right column of the Home screen with additional sections and static links. It is really simple extensibility and should be used as interim solution until the new HTML 5 UI will fully replace the existing UI and which will be more extensible.

In the screenshot below you can see that the right section has been extended with vCloud Availability, Backup and Other sections.

The configuration of these links is very simple and is done from cell-management-tool on any vCloud cell.

In my example I used:

./cell-management-tool manage-config -n ui.tenant.customOrgLinks -v “
# vCloud Availability
[Monitor Replications](
# Backup
[Configure Backup](
# Other
[Request Support](

Where # denotes the section header, [] the link name and () the link.

It is also possible to pass vCloud session ID as parameter in the URL by including {vcdSession} string.

The CMT manage-config command creates/modifies database entry in the config table tenant-customOrgLinks with the provided value in the quotes. Re-running it will replace the previous entry. The change is immediate, no need to run this on other cells or restart vcd services.

One last note, the right column on the home screen is not visible to all user roles. The role needs to have General > Administrator Control right.

Defer to Identity Provider Role in vCloud Director

Besides traditional roles (Org Administrator, vApp Author, …) there is already for some time (as of vCloud Director 8.0) the possibility to assign to vCloud Director organization users a role called ‘Defer to Identity Provider’.

I am going to show how this role can be used to manage assignments of organization roles centrally from within the Identity Provider (IdP) and not from vCloud Director at the Organization level. Central management might be beneficial in cases where there are many Organizations (and vCloud Director instances) associated with single IdP and one user might have access to multiple Organizations. With the traditional approach the user (or his group) would have to be imported into each Organization where he/she should have access and assigned a role.

By deferring to identity provider we rely on the IdP to provide the user’s role just in time when the user is logging in. The feature works both with SAML and OAuth identity providers. In my example I am going to be using the SAML IdP provided by Active Director Federation Services federated with vCloud Director as described in my older blog post.

The set up:

  • Active Directory is used to manage all the users (with exception of local user for onboarding or troubleshooting purposes). The AD can be owned by the Service Provider or the tenant, it depends on the use case.
  • AD FS has been deployed and integrated with vCloud Director Organizations. Note that each Organization must be federated with AD FS specifically. And the federation must be refreshed every year by regeneration of new certificate. In SP use case some level of automation is essential. For details refer to the blog article linked above.
  • AD users who should have access to vCloud Director organization will be part of AD group <Tenant_X>.
  • Role association will be achieved by assigning the AD users to specific AD groups: Organization Administrator, vApp Author, …
  • For each role we will need to add new Transform Claim Rule in AD FS.
    1. On the existing relaying party trust click Edit Claim Rules
    2. Click Add Rule
    3. Select Send Group Membership as a Claim template
    4. Name the rule (e.g. vApp Author)
    5. Browse to the User’s group that represents the role membership (vApp Author group)
    6. In Outgoing claim type select Role.
    7. In Outgoing claim value type the vCloud Director role name (vApp Author).
  • In vCloud Director Organization we need to do following:
    1. As already mentioned each Org needs to be federated with AD FS
    2. In Members > Groups import the <Tenant X> group from Source: SAML with Role: Defer to Identity Provider.
    3. With vCloud API specify RoleAttributeName in OrgFederationSettings. The name for AD FS should be:

Now the users can start logging in with their AD accounts and they will be automatically imported as users with Defer to IdP role. If needed, you can still directly import SAML users and specifically give them role which will take precedence over the IdP role.


Org VDC Edge Gateway CPU/RAM Reservations

vCloud Director 8.20 allows deployment of Org VDC Edge Gateways in 4 different form factors from Compact to X-Large where each provides different level of performance and consumes different amount of resources.

As these Edge Gateways are deployed by NSX Manager which allows setting custom reservations for CPU and RAM via an API call PUT https://<NSXManager>/api/4.0/edgePublish/tuningConfiguration, it is also possible in vCloud Director to set custom reservations.

Why would you change the default reservations? Reservations at VM (Edge) level reserve the resources for itself which means no other VM can utilize them in case they are unused. They basically guarantee certain level of service that the VM (Edge) from performance perspective will always deliver. In service provider environments oversubscription provides ROI benefits and if the service provider can guarantee enough resources at cluster scale, than the VM level reservations can be set lower if at all.

This can be accomplished by tuning the networking.gatewayMemoryReservationMultiplier and networking.gatewayCpuReservationMultiplier settings via cell-management-tool from vCloud Director cell. By default the CPU multiplier is set to 64 MHz per vCPU and the Memory multiplier to 0.5.

By default Edge Gateways will be deployed with the following reservation settings:

Org VDC Edge GW Default Resource Reservations

The following command will change memory multiplier to 10%:

/opt/vmware/vcloud-director/bin/cell-management-tool manage-config -n networking.gatewayMemoryReservationMultiplier -v 0.1

Note: The new reservation settings are applicable only for newly deployed Org VDC Edge Gateways. Redeploying existing edges will not change their reservation settings. You must either use NSX API to do so, or modify Org VDC Edge Gateway form factor (e.g. change Large to Compact and then back to Large) which is not so elegant as it will basically redeploy the Edge twice.

Also note that NSX 6.2 and NSX 6.3 have different sizing of Quad Large Edge. vCloud Director 8.20 is by default set for the NSX 6.3 size which is 2 GB RAM (as opposed to NSX 6.2 value of 1 GB RAM). It is possible to change the default for the reservation calculation by editing networking.full4GatewayMemoryMb setting to value ‘1024’

How to Export Running VM from vCloud Director

In the past I have wrote how to import running VM to vCloud Director: here and here. Today, I will describe how to export running VM.

Let us first discuss why you would do it. There are several use cases:

  • you want to manage the VM by a different Cloud Management Platform (for example vRealize Automation)
  • you want to migrate (utilizing cross VC vMotion) to a different vCloud Director
  • you want to move the VM to a different Org VDC

Currently (as of vCloud Director 8.20) there is no direct way to export running VM. So the procedure I will describe below is kind of a workaround. But let me first describe, what it means for a VM to be managed by vCloud Director.

  • VM is ‘marked’ at vSphere level with Custom Attributes and ManagedBy extension.
  • VM has its cloud_uuid stored in its configuration parameters
  • VM has assigned CPU/RAM reservations and limits depending on its Org VDC allocation model
  • VM is running in resource pool and folder based on its Org VDC/vApp
  • VM has a name that includes its UUID
  • vCloud Director is tracking the VM in vSphere inventory even if it changes its name, location and MoRef ID.
  • vCloud Director is reserving VMs IP and MAC addresses in its IPAM.
  • vCloud Director is counting VMs resources to its Org VDC allocation.

In order to remove the VM from vCloud Director management we must take care of all these points.

Here comes the procedure I came up with. It can obviously be automated with vSphere and vCloud APIs if needed for export of large amount of VMs.

First we clean up VM at vSphere level in vCenter Server:

  1. Move VM outside the vCloud Director managed Resource Pool (this is to avoid auto-import of the VM)
  2. If necessary reconnect VM to network not managed by vCloud Director (this is for situations where the vApp or Org VDC network is going to be deleted later). Obviously as the VM is running, the new network should provide equivalent connectivity as the original one (either with L2 bridging or routing).
  3. Remove cloud-uuid from the VM configuration parameters. This can be done on running VM with PowerCLI:
    (Get-AdvancedSetting -entity $vm -Name cloud.uuid)|Remove-AdvancedSetting
  4. Remove vCloud Director related Custom Attribute values (in my case VCD_fojta_01). Do not remove the whole Custom Attribute, just the value.
  5. Remove ManagedBy extension from the VM. The easiest to do is leveraging PowerCLI script attached to KB 2032366. You will see the VM icon has changed after the extension has been removed.
    \ManagedBy.ps1 -Cmd Clear -VMs $vm
  6. Remove VM resource reservation and limits (if applicable).
  7. Rename VM (to get rid of UUID in the name).
    Now we need to take care of removing VM in vCloud Director, however even though we removed its cloud-uuid vCloud Director still sees the VM through its vCenter MoRef ID. And we cannot change MoRef ID of running VM. So here comes the workaround:
  8. Temporarily remove access to the VM for vCloud Director service account (account configured in vCloud Director for the particular vCenter Server). To do so, you assign No Access role permission on the VM object for the service account user.
  9. Now the VM has become invisible for vCloud Director and we can clean it up in vCloud Director. First Force-Stop its vApp.
  10. Now Delete the vApp. Ignore the error.
  11. Purge the vApp from stranded items with Force Delete.
  12. Now we can remove the temporary no access role permission from step #8.
  13. Clean up the vApp folder in vCenter Server if it was not removed.

Quite lengthy and not pretty procedure, however we did not do anything unsupported (like editing vCloud database) and the VM has been properly removed from vCloud Director inventory.

Last comment is about VM MAC addresses. If the VM was created in vCloud Director it will have MAC addresses from the vCloud Director range based on VCD installation ID. Have that in mind when moving VM around as duplicate MACs could be generated.