Add a force_replace_host flag to win_domain_membership (#53542)

* Add a force_replace_host flag to win_domain_membership

Satisfies https://github.com/ansible/ansible/issues/53539

* Rework backticks

* Bump version_added

* Check for existence of current hostname as well; use LDAPFilter during search

* Rename $force_replace_host to $allow_existing_computer_account

* Added docs, porting guide and minor nit in code

changelogs/fragments/win_domain_membership-replace.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+- win_domain_membership - will now fail if an existing AD object for the host exists and ``allow_existing_computer_account=no`` - https://github.com/ansible/ansible/pull/53542

docs/docsite/rst/porting_guides/porting_guide_2.8.rst

@@ -315,6 +315,10 @@ Noteworthy module changes
 * The ``win_dsc`` module will now validate the input options for a DSC resource. In previous versions invalid options
   would be ignored but are now not.
 
+* The ``win_domain_membership`` module will no longer automatically join a host in a domain that already has an account
+  with the same name. Set ``allow_existing_computer_account=yes`` to override this check and go back to the original
+  behaviour.
+
 Plugins
 =======
 

lib/ansible/modules/windows/win_domain_membership.ps1

@@ -102,7 +102,8 @@ Function Join-Domain {
         [string] $new_hostname,
         [string] $domain_admin_user,
         [string] $domain_admin_password,
-        [string] $domain_ou_path
+        [string] $domain_ou_path,
+        [bool]   $allow_existing_computer_account
     )
 
     Write-DebugLog ("Creating credential for user {0}" -f $domain_admin_user)
@@ -118,17 +119,24 @@ Function Join-Domain {
     Write-DebugLog "adding hostname set arg to Add-Computer args"
     If($new_hostname) {
         $add_args["NewName"] = $new_hostname
+        $hostname_in_domain = Get-ADObject -LDAPFilter "(&(CN=$new_hostname)(ObjectClass=Computer))"
+    } else {
+        $hostname_in_domain = Get-ADObject -LDAPFilter "(&(CN=$env:COMPUTERNAME)(ObjectClass=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"
     try {
-        $add_result = Add-Computer @add_args
+        if($null -eq $hostname_in_domain -or ($null -ne $hostname_in_domain -and $allow_existing_computer_account)) {
+            $add_result = Add-Computer @add_args
+        } else {
+            Fail-Json -obj $result -message "failed to join domain: hostname already exists in AD and allow_existing_computer_account=no"
+        }
     } catch {
         Fail-Json -obj $result -message "failed to join domain: $($_.Exception.Message)"
     }
@@ -198,6 +206,7 @@ $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"
+$allow_existing_computer_account = Get-AnsibleParam $params "allow_existing_computer_account" -type "bool" -default $false
 
 $log_path = Get-AnsibleParam $params "log_path"
 $_ansible_check_mode = Get-AnsibleParam $params "_ansible_check_mode" -default $false
@@ -239,6 +248,7 @@ Try {
                         dns_domain_name = $dns_domain_name
                         domain_admin_user = $domain_admin_user
                         domain_admin_password = $domain_admin_password
+                        allow_existing_computer_account = $allow_existing_computer_account
                     }
 
                     Write-DebugLog "not a domain member, joining..."

lib/ansible/modules/windows/win_domain_membership.py

@@ -48,6 +48,13 @@ options:
     description:
       - When C(state) is C(workgroup), the name of the workgroup that the Windows host should be in.
     type: str
+  allow_existing_computer_account:
+    description:
+      - If a host with the same hostname is already in the AD, replace it.
+    type: bool
+    choices: [ true, false ]
+    default: false
+    version_added: "2.8"
 seealso:
 - module: win_domain
 - module: win_domain_controller

test/sanity/pslint/ignore.txt

@@ -57,7 +57,6 @@ lib/ansible/modules/windows/win_domain_controller.ps1 PSUseApprovedVerbs
 lib/ansible/modules/windows/win_domain_controller.ps1 PSUseDeclaredVarsMoreThanAssignments
 lib/ansible/modules/windows/win_domain_group.ps1 PSAvoidTrailingWhitespace
 lib/ansible/modules/windows/win_domain_membership.ps1 PSAvoidGlobalVars
-lib/ansible/modules/windows/win_domain_membership.ps1 PSAvoidTrailingWhitespace
 lib/ansible/modules/windows/win_domain_membership.ps1 PSAvoidUsingWMICmdlet
 lib/ansible/modules/windows/win_domain_membership.ps1 PSCustomUseLiteralPath
 lib/ansible/modules/windows/win_domain_membership.ps1 PSUseApprovedVerbs