win_domain_controller: add readonly support (#33850)

* win_domain_controller: add readonly and sitename functionality

* fixed minor typo

* removed choices from doc

lib/ansible/modules/windows/win_domain_controller.ps1

@@ -1,24 +1,10 @@
 #!powershell
-
-# (c) 2017, Red Hat, Inc.
-#
 # This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
-# WANT_JSON
+# Copyright: (c) 2017, Red Hat, Inc.
-# POWERSHELL_COMMON
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#Requires -Module Ansible.ModuleUtils.Legacy
 
 Set-StrictMode -Version 2
 
@@ -118,6 +104,8 @@ $domain_admin_password= Get-AnsibleParam $param "domain_admin_password" -failife
 $local_admin_password= Get-AnsibleParam $param "local_admin_password"
 $database_path = Get-AnsibleParam $param "database_path" -type "path"
 $sysvol_path = Get-AnsibleParam $param "sysvol_path" -type "path"
+$read_only = Get-AnsibleParam $param "read_only" -type "bool" -default $false
+$site_name = Get-AnsibleParam $param "site_name" -type "str" -failifempty $read_only
 
 $state = Get-AnsibleParam $param "state" -validateset ("domain_controller", "member_server") -failifempty $result
 $log_path = Get-AnsibleParam $param "log_path"
@@ -216,7 +204,10 @@ Try {
                 if ($sysvol_path) {
                     $install_params.SysvolPath = $sysvol_path
                 }
-                $install_result = Install-ADDSDomainController -NoRebootOnCompletion -Force @install_params
+                if ($site_name) {
+                    $install_params.SiteName = $site_name
+                }
+                $install_result = Install-ADDSDomainController -NoRebootOnCompletion -ReadOnlyReplica:$read_only -Force @install_params
 
                 Write-DebugLog "Installation completed, needs reboot..."
             }

lib/ansible/modules/windows/win_domain_controller.py

@@ -1,22 +1,11 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Red Hat, Inc.
-#
 # This file is part of Ansible
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+# (c) 2017, Red Hat, Inc.
-# it under the terms of the GNU General Public License as published by
+# Copyright (c) 2017 Ansible Project
-# the Free Software Foundation, either version 3 of the License, or
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
@@ -33,24 +22,37 @@ description:
 options:
   dns_domain_name:
     description:
-      - when C(state) is C(domain_controller), the DNS name of the domain for which the targeted Windows host should be a DC
+      - When C(state) is C(domain_controller), the DNS name of the domain for which the targeted Windows host should be a DC.
   domain_admin_user:
     description:
-      - username of a domain admin for the target domain (necessary to promote or demote a domain controller)
+      - Username of a domain admin for the target domain (necessary to promote or demote a domain controller).
     required: true
   domain_admin_password:
     description:
-      - password for the specified C(domain_admin_user)
+      - Password for the specified C(domain_admin_user).
     required: true
   safe_mode_password:
     description:
-      - safe mode password for the domain controller (required when C(state) is C(domain_controller))
+      - Safe mode password for the domain controller (required when C(state) is C(domain_controller)).
   local_admin_password:
     description:
-      - password to be assigned to the local C(Administrator) user (required when C(state) is C(member_server))
+      - Password to be assigned to the local C(Administrator) user (required when C(state) is C(member_server)).
+  read_only:
+    description:
+      - Whether to install the domain controller as a read only replica for an
+        existing domain.
+    type: bool
+    default: 'no'
+    version_added: '2.5'
+  site_name:
+    description:
+      - Specifies the name of an existing site where you can place the new
+        domain controller.
+      - This option is required when I(read_only) is C(yes).
+    version_added: '2.5'
   state:
     description:
-      - whether the target host should be a domain controller or a member server
+      - Whether the target host should be a domain controller or a member server.
     choices:
       - domain_controller
       - member_server
@@ -80,17 +82,14 @@ reboot_required:
 '''
 
 EXAMPLES = r'''
-# ensure a server is a domain controller
+- name: ensure a server is a domain controller
-- hosts: winclient
+  win_domain_controller:
-  gather_facts: no
+    dns_domain_name: ansible.vagrant
-  tasks:
+    domain_admin_user: testguy@ansible.vagrant
-  - win_domain_controller:
+    domain_admin_password: password123!
-      dns_domain_name: ansible.vagrant
+    safe_mode_password: password123!
-      domain_admin_user: testguy@ansible.vagrant
+    state: domain_controller
-      domain_admin_password: password123!
+    log_path: c:\ansible_win_domain_controller.txt
-      safe_mode_password: password123!
-      state: domain_controller
-      log_path: c:\ansible_win_domain_controller.txt
 
 # ensure a server is not a domain controller
 # note that without an action wrapper, in the case where a DC is demoted,
@@ -98,14 +97,20 @@ EXAMPLES = r'''
 # becomes invalid to fetch the final output over WinRM. This requires win_async
 # with credential switching (or other clever credential-switching
 # mechanism to get the output and trigger the required reboot)
-- hosts: winclient
+- win_domain_controller:
-  gather_facts: no
+    domain_admin_user: testguy@ansible.vagrant
-  tasks:
+    domain_admin_password: password123!
-  - win_domain_controller:
+    local_admin_password: password123!
-      domain_admin_user: testguy@ansible.vagrant
+    state: member_server
-      domain_admin_password: password123!
+    log_path: c:\ansible_win_domain_controller.txt
-      local_admin_password: password123!
-      state: member_server
-      log_path: c:\ansible_win_domain_controller.txt
 
+- name: promote server as a read only domain controller
+  win_domain_controller:
+    dns_domain_name: ansible.vagrant
+    domain_admin_user: testguy@ansible.vagrant
+    domain_admin_password: password123!
+    safe_mode_password: password123!
+    state: domain_controller
+    read_only: yes
+    site_name: London
 '''