Joining VMs to Active Directory in site-specific OUs with vRA8

Technology keeps moving but this post has not.

What you're about to read hasn't been updated in more than a year. The information may be out of date. Let me know if you see anything that needs fixing.

Connecting a deployed Windows VM to an Active Directory domain is pretty easy; just apply an appropriately-configured customization spec and vCenter will take care of it for you. Of course, you'll likely then need to move the newly-created computer object to the correct Organizational Unit so that it gets all the right policies and such.

Fortunately, vRA 8 supports adding an Active Directory integration to handle staging computer objects in a designated OU. And vRA 8.3 even introduced the ability to let blueprints override the relative DN path. That will be helpful in my case since I'll want the servers to be placed in different OUs depending on which site they get deployed to:

Site OU

I didn't find a lot of documentation on how make this work, though, so here's how I've implemented it in my lab (now running vRA 8.4.2).

Adding the AD integration

First things first: connecting vRA to AD. I do this by opening the Cloud Assembly interface, navigating to Infrastructure > Connections > Integrations, and clicking the Add Integration button. I'm then prompted to choose the integration type so I select the Active Directory one, and then I fill in the required information: a name (Lab AD seems appropriate), my domain controller as the LDAP host (ldap://, credentials for an account with sufficient privileges to create and delete computer objects (lab\vra), and finally the base DN to be used for the LDAP connection (DC=lab,DC=bowdre,DC=net).

Creating the new AD integration

Clicking the Validate button quickly confirms that I've entered the information correctly, and then I can click Add to save my work.

I'll then need to associate the integration with a project by opening the new integration, navigating to the Projects tab, and clicking Add Project. Now I select the project name from the dropdown, enter a valid relative OU (OU=LAB), and enable the options to let me override the relative OU and optionally skip AD actions from the cloud template.

Project options for the AD integration

Customization specs

As mentioned above, I'll leverage the customization specs in vCenter to handle the actual joining of a computer to the domain. I maintain two specs for Windows deployments (one to join the domain and one to stay on the workgroup), and I can let the vRA cloud template decide which should be applied to a given deployment.

First, the workgroup spec, appropriately called vra-win-workgroup: Workgroup spec

It's about as basic as can be, including using DHCP for the network configuration (which doesn't really matter since the VM will eventually get a static IP assigned from {php}IPAM).

vra-win-domain is basically the same, with one difference: Domain spec

Now to reference these specs from a cloud template...

Cloud template

I want to make sure that users requesting a deployment are able to pick whether or not a system should be joined to the domain, so I'm going to add that as an input option on the template:

2  [...]
3  adJoin:
4    title: Join to AD domain
5    type: boolean
6    default: true
7  [...]

This new adJoin input is a boolean so it will appear on the request form as a checkbox, and it will default to true; we'll assume that any Windows deployment should be automatically joined to AD unless this option gets unchecked.

In the resources section of the template, I'll set a new property called ignoreActiveDirectory to be the inverse of the adJoin input; that will tell the AD integration not to do anything if the box to join the VM to the domain is unchecked. I'll also use activeDirectory: relativeDN to insert the appropriate site code into the DN where the computer object will be created. And, finally, I'll reference the customizationSpec and use cloud template conditional syntax to apply the correct spec based on whether it's a domain or workgroup deployment. (These conditionals take the pattern '${conditional-expresion ? true-value : false-value}').

 2  Cloud_vSphere_Machine_1:
 3    type: Cloud.vSphere.Machine
 4    properties:
 5      [...]
 6      ignoreActiveDirectory: '${!input.adJoin}'
 7      activeDirectory:
 8        relativeDN: '${"OU=Servers,OU=Computers,OU=" + + ",OU=LAB"}'
 9      customizationSpec: '${input.adJoin ? "vra-win-domain" : "vra-win-workgroup"}'
10      [...]

Here's the current cloud template in its entirety:

  1formatVersion: 1
  3  site:
  4    type: string
  5    title: Site
  6    enum:
  7      - BOW
  8      - DRE
  9  image:
 10    type: string
 11    title: Operating System
 12    oneOf:
 13      - title: Windows Server 2019
 14        const: ws2019
 15    default: ws2019
 16  size:
 17    title: Resource Size
 18    type: string
 19    oneOf:
 20      - title: 'Micro [1vCPU|1GB]'
 21        const: micro
 22      - title: 'Tiny [1vCPU|2GB]'
 23        const: tiny
 24      - title: 'Small [2vCPU|2GB]'
 25        const: small
 26    default: small
 27  network:
 28    title: Network
 29    type: string
 30  adJoin:
 31    title: Join to AD domain
 32    type: boolean
 33    default: true
 34  environment:
 35    type: string
 36    title: Environment
 37    oneOf:
 38      - title: Development
 39        const: D
 40      - title: Testing
 41        const: T
 42      - title: Production
 43        const: P
 44    default: D
 45  function:
 46    type: string
 47    title: Function Code
 48    oneOf:
 49      - title: Application (APP)
 50        const: APP
 51      - title: Desktop (DSK)
 52        const: DSK
 53      - title: Network (NET)
 54        const: NET
 55      - title: Service (SVS)
 56        const: SVS
 57      - title: Testing (TST)
 58        const: TST
 59    default: TST
 60  app:
 61    type: string
 62    title: Application Code
 63    minLength: 3
 64    maxLength: 3
 65    default: xxx
 66  description:
 67    type: string
 68    title: Description
 69    description: Server function/purpose
 70    default: Testing and evaluation
 71  poc_name:
 72    type: string
 73    title: Point of Contact Name
 74    default: Jack Shephard
 75  poc_email:
 76    type: string
 77    title: Point of Contact Email
 78    default:
 79    pattern: '^[^\s@]+@[^\s@]+\.[^\s@]+$'
 80  ticket:
 81    type: string
 82    title: Ticket/Request Number
 83    default: 4815162342
 85  Cloud_vSphere_Machine_1:
 86    type: Cloud.vSphere.Machine
 87    properties:
 88      image: '${input.image}'
 89      flavor: '${input.size}'
 90      site: '${}'
 91      environment: '${input.environment}'
 92      function: '${input.function}'
 93      app: '${}'
 94      ignoreActiveDirectory: '${!input.adJoin}'
 95      activeDirectory:
 96        relativeDN: '${"OU=Servers,OU=Computers,OU=" + + ",OU=LAB"}'
 97      customizationSpec: '${input.adJoin ? "vra-win-domain" : "vra-win-workgroup"}'
 98      dnsDomain:
 99      poc: '${input.poc_name + " (" + input.poc_email + ")"}'
100      ticket: '${input.ticket}'
101      description: '${input.description}'
102      networks:
103        - network: '${}'
104          assignment: static
105      constraints:
106        - tag: 'comp:${to_lower(}'
107  Cloud_vSphere_Network_1:
108    type: Cloud.vSphere.Network
109    properties:
110      networkType: existing
111      constraints:
112        - tag: 'net:${}'

The last thing I need to do before leaving the Cloud Assembly interface is smash that Version button at the bottom of the cloud template editor so that the changes will be visible to Service Broker: New version

Service Broker custom form updates

... and the first thing to do after entering the Service Broker UI is to navigate to Content Sources, click on my Lab content source, and then click Save & Import to bring in the new version. I can then go to Content, click the little three-dot menu icon next to my WindowsDemo cloud template, and pick the Customize form option.

This bit will be pretty quick. I just need to look for the new Join to AD domain element on the left: New element on left

And drag-and-drop it onto the canvas in the middle. I'll stick it directly after the Network field: New element on the canvas

I don't need to do anything else here since I'm not trying to do any fancy logic or anything, so I'll just hit Save and move on to...


Now to submit the request through Service Broker to see if this actually works: Submitting the request

After a few minutes, I can go into Cloud Assembly and navigate to Extensibility > Activity > Actions Runs and look at the Integration Runs to see if the ad_machine action has completed yet. Successful ad_machine action

Looking good! And once the deployment completes, I can look at the VM in vCenter to see that it has registered a fully-qualified DNS name since it was automatically joined to the domain: Domain-joined VM

I can also repeat the test for a VM deployed to the DRE site just to confirm that it gets correctly placed in that site's OU: Another domain-joined VM

And I'll fire off another deployment with the adJoin box unchecked to test that I can also skip the AD configuration completely: VM not joined to the domain


Confession time: I had actually started writing this posts weeks ago. At that point, my efforts to bend the built-in AD integration to my will had been fairly unsuccessful, so I was instead working on a custom vRO workflow to accomplish the same basic thing. I circled back to try the AD integration again after upgrading the vRA environment to the latest 8.4.2 release, and found that it actually works quite well now. So I happily scrapped my ~50 lines of messy vRO JavaScript in favor of just three lines of YAML in the cloud template.

I love it when things work out!