Added ability to specify destination OU when joining a domain (#22393)

* Added ability to specify destination OU when joining a domain

* Updated win_domain_membership documentation to include OU destination option.

* Updated python to include version

* Additional info in the docs

lib/ansible/modules/windows/win_domain_membership.ps1

@@ -99,7 +99,8 @@ Function Join-Domain {
         [string] $dns_domain_name,
         [string] $new_hostname,
         [string] $domain_admin_user,
-        [string] $domain_admin_password
+        [string] $domain_admin_password,
+        [string] $domain_ou_path
     )
 
     Write-DebugLog ("Creating credential for user {0}" -f $domain_admin_user)
@@ -117,7 +118,13 @@ Function Join-Domain {
         $add_args["NewName"] = $new_hostname
     }
 
-    Write-DebugLog "calling Add-Computer"
+
+    if($domain_ou_path){
+        Write-DebugLog "adding OU destination arg to Add-Computer args"
+        $add_args["OUPath"] = $domain_ou_path
+    }
+    $argstr = $add_args | Out-String
+    Write-DebugLog "calling Add-Computer with args: $argstr"
     $add_result = Add-Computer @add_args
 
     Write-DebugLog ("Add-Computer result was \n{0}" -f $add_result | Out-String)
@@ -172,6 +179,7 @@ $hostname = Get-AnsibleParam $params "hostname"
 $workgroup_name = Get-AnsibleParam $params "workgroup_name"
 $domain_admin_user = Get-AnsibleParam $params "domain_admin_user" -failifempty $result
 $domain_admin_password = Get-AnsibleParam $params "domain_admin_password" -failifempty $result
+$domain_ou_path = Get-AnsibleParam $params "domain_ou_path"
 
 $log_path = Get-AnsibleParam $params "log_path"
 $_ansible_check_mode = Get-AnsibleParam $params "_ansible_check_mode" -default $false
@@ -221,6 +229,10 @@ Try {
                         Write-DebugLog "adding hostname change to domain-join args"
                         $join_args.new_hostname = $hostname
                     }
+                    If($domain_ou_path -ne $null){ # If OU Path is not empty
+                        Write-DebugLog "adding domain_ou_path to domain-join args"
+                        $join_args.domain_ou_path = $domain_ou_path
+                    }
 
                     $join_result = Join-Domain @join_args
                 }
@@ -276,4 +288,3 @@ Catch {
 
     Throw
 }
-

lib/ansible/modules/windows/win_domain_membership.py

@@ -45,6 +45,11 @@ options:
   hostname:
     description:
       - the desired hostname for the Windows host
+  domain_ou_path:
+    description:
+      - The desired OU path for adding the computer object.
+      - This is only used when adding the target host to a domain, if it is already a member then it is ignored.
+    version_added: "2.4"
   state:
     description:
       - whether the target host should be a member of a domain or workgroup
@@ -80,6 +85,7 @@ EXAMPLES = '''
       hostname: mydomainclient
       domain_admin_user: testguy@ansible.vagrant
       domain_admin_password: password123!
+      domain_ou_path: "OU=Windows,OU=Servers,DC=ansible,DC=vagrant"
       state: domain
     register: domain_state