microsoft.ad.domain_controller module – Manage domain controller/member server state for a Windows host

Note

This module is part of the microsoft.ad collection (version 1.8.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install microsoft.ad.

To use it in a playbook, specify: microsoft.ad.domain_controller.

Synopsis

• Ensure that a Windows Server 2012+ host is configured as a domain controller or demoted to member server.

• This module may require subsequent use of the ansible.windows.win_reboot action if changes are made.

Note

This module has a corresponding action plugin.

Parameters

Parameter	Comments
database_path path	The path to a directory on a fixed disk of the Windows host where the domain database will be created.. If not set then the default path is %SYSTEMROOT%\NTDS.
dns_domain_name string	When state=domain_controller, the DNS name of the domain for which the targeted Windows host should be a DC.
domain_admin_password string / required	Password for the specified domain_admin_user.
domain_admin_user string / required	Username of a domain admin for the target domain (necessary to promote or demote a domain controller).
domain_log_path path	Specified the fully qualified, non-UNC path to a directory on a fixed disk of the local computer that will contain the domain log files.
install_dns boolean	Whether to install the DNS service when creating the domain controller. If not specified then the -InstallDns option is not supplied to Install-ADDSDomainController command, see Install-ADDSDomainController. Choices: false true
install_media_path path	The path to a directory on a fixed disk of the Windows host where the Install From Media IFC data will be used. See the Install using IFM guide for more information.
local_admin_password string	Password to be assigned to the local Administrator user (required when state=member_server).
read_only boolean	Whether to install the domain controller as a read only replica for an existing domain. Choices: false ← (default) true
reboot boolean	If true, this will reboot the host if a reboot was required by the module. If false, this will not reboot the host if a reboot was required and instead sets the reboot_required return value to true. This cannot be used with async mode. Choices: false ← (default) true
reboot_timeout integer added in microsoft.ad 1.7.0	Maximum seconds to wait for machine to re-appear after a reboot and respond to a test command. This timeout is evaluated separately for both the reboot verification and test command success so the total timeout can be twice this value. Default: 600
replication_source_dc string added in microsoft.ad 1.8.0	Specifies the name of an existing domain controller in the forest that will be used as the replication source for the new domain controller.
safe_mode_password string	Safe mode password for the domain controller (required when state=domain_controller).
site_name string	Specifies the name of an existing site where you can place the new domain controller. This option is required when read_only=true.
state string / required	Whether the target host should be a domain controller or a member server. Choices: "domain_controller" "member_server"
sysvol_path path	The path to a directory on a fixed disk of the Windows host where the Sysvol folder will be created. If not set then the default path is %SYSTEMROOT%\SYSVOL.

Attributes

Attribute	Support	Description
action	Support: full	Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller
async	Support: partial Supported for all scenarios except with reboot=True.	Supports being used with the async keyword
bypass_host_loop	Support: none	Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations Conditionals will work as if run_once is being used, variables used will be from the first available host This action will not work normally outside of lockstep strategies
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: windows	Target OS/families that can be operated against

Notes

Note

• It is highly recommended to set reboot=true to have Ansible manage the host reboot phase as the actions done by this module puts the host in a state where it may not be possible for Ansible to reconnect in a subsequent task without a reboot.

• This module must be run on a Windows target host.

• If using reboot=true, multiple reboots may occur if the host required a reboot before the domain promotion. Also ensure the fully qualified module name is used in the task or the collections keyword includes this collection.

See Also

See also

microsoft.ad.computer

Manage Active Directory computer objects.

microsoft.ad.domain

Ensures the existence of a Windows domain.

microsoft.ad.domain_child

Manage domain children in an existing Active Directory forest.

microsoft.ad.group

Manage Active Directory group objects.

microsoft.ad.membership

Manage domain/workgroup membership for a Windows host.

microsoft.ad.user

Manage Active Directory users.

Migration guide

This module replaces ansible.windows.win_domain_controller. See the migration guide for details.

ansible.windows.win_domain_controller

Manage domain controller/member server state for a Windows host.

Examples

- name: Ensure a server is a domain controller
  microsoft.ad.domain_controller:
    dns_domain_name: ansible.vagrant
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    safe_mode_password: password123!
    state: domain_controller
    reboot: true

- name: Ensure a server is not a domain controller
  microsoft.ad.domain_controller:
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    local_admin_password: password123!
    state: member_server
    reboot: true

- name: Promote server as a read only domain controller
  microsoft.ad.domain_controller:
    dns_domain_name: ansible.vagrant
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    safe_mode_password: password123!
    state: domain_controller
    read_only: true
    site_name: London
    reboot: true

# This scenario is not recommended, use reboot: true when possible
- name: Promote server with custom paths with manual reboot task
  microsoft.ad.domain_controller:
    dns_domain_name: ansible.vagrant
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    safe_mode_password: password123!
    state: domain_controller
    sysvol_path: D:\SYSVOL
    database_path: D:\NTDS
    domain_log_path: D:\NTDS
  register: dc_promotion

- name: Reboot after promotion
  ansible.windows.win_reboot:
  when: dc_promotion.reboot_required

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
reboot_required boolean	True if changes were made that require a reboot. Returned: always Sample: true

Authors

• Matt Davis (@nitzmahone)

• Jordan Borean (@jborean93)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication