Note
This module is part of the microsoft.ad collection (version 1.9.2).
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.
Note
This module has a corresponding action plugin.
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 |
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 Choices:
|
install_media_path path | 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. |
local_admin_password string | Password to be assigned to the local |
read_only boolean | Whether to install the domain controller as a read only replica for an existing domain. Choices:
|
reboot boolean | If If This cannot be used with async mode. Choices:
|
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: |
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:
|
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 |
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 |
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 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 |
Note
See also
Manage Active Directory computer objects.
Ensures the existence of a Windows domain.
Manage domain children in an existing Active Directory forest.
Manage Active Directory group objects.
Manage domain/workgroup membership for a Windows host.
Manage Active Directory users.
This module replaces ansible.windows.win_domain_controller. See the migration guide for details.
Manage domain controller/member server state for a Windows host.
- 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
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: |
© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/microsoft/ad/domain_controller_module.html