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.7.1).
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 |
|---|---|
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 |
|
When state=domain_controller, the DNS name of the domain for which the targeted Windows host should be a DC. |
|
Password for the specified domain_admin_user. |
|
Username of a domain admin for the target domain (necessary to promote or demote a domain controller). |
|
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. |
|
Whether to install the DNS service when creating the domain controller. If not specified then the Choices:
|
|
The path to a directory on a fixed disk of the Windows host where the Install From Media See the Install using IFM guide for more information. |
|
Password to be assigned to the local |
|
Whether to install the domain controller as a read only replica for an existing domain. Choices:
|
|
If If This cannot be used with async mode. Choices:
|
|
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: |
|
Safe mode password for the domain controller (required when state=domain_controller). |
|
Specifies the name of an existing site where you can place the new domain controller. This option is required when read_only=true. |
|
Whether the target host should be a domain controller or a member server. Choices:
|
|
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 |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller |
|
Support: partial Supported for all scenarios except with reboot=True. |
Supports being used with the |
|
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 This action will not work normally outside of lockstep strategies |
|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
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 |
|---|---|
True if changes were made that require a reboot. Returned: always Sample: |