microsoft.ad.domain_child module – Manage domain children in an existing Active Directory forest.
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_child.
New in microsoft.ad 1.6.0
Synopsis
Ensure that a Windows Server host is configured as a domain controller as a new domain in an existing forest.
This module may require subsequent use of the ansible.windows.win_reboot action if changes are made.
This module will only check if the domain specified by dns_domain_name exists or not. If the domain already exists under the same name, no other options, other than the domain name will be checked during the run.
Note
This module has a corresponding action plugin.
Parameters
Parameter |
Comments |
|---|---|
Whether to create a DNS delegation that references the new DNS server that was installed. Valid for Active Directory-integrated DNS only. The default is computed automatically based on the environment. Choices:
|
|
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 |
|
The full DNS name of the domain to create. When domain_type=child, the parent DNS domain name is derived from this value. |
|
Password for the specified domain_admin_user. |
|
Username of a domain admin for the parent domain. |
|
Specifies the domain functional level of child/tree. The domain functional level cannot be lower than the forest functional level, but it can be higher. The default is automatically computed and set. Current known modes are |
|
Specifies the type of domain to create. Set to Set to Choices:
|
|
Whether to install the DNS service when creating the domain controller. If not specified then the Choices:
|
|
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. |
|
The fully qualified domain name of an existing parent domain to create a new domain tree in. This can only be set when domain_type=tree. |
|
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. |
|
Specifies the name of an existing site where you can place the new domain controller. |
|
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 |
|
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.
See Also
See also
- microsoft.ad.domain
Ensures the existence of a Windows domain.
- microsoft.ad.domain_controller
Manage domain controller/member server state for a Windows host.
Examples
- name: Create a child domain foo.example.com with parent example.com
microsoft.ad.domain_child:
dns_domain_name: foo.example.com
domain_admin_user: [email protected]
domain_admin_password: password123!
safe_mode_password: password123!
reboot: true
- name: Create a domain tree foo.example.com with parent bar.example.com
microsoft.ad.domain_child:
dns_domain_name: foo.example.com
parent_domain_name: bar.example.com
domain_type: tree
domain_admin_user: [email protected]
domain_admin_password: password123!
local_admin_password: password123!
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_child:
dns_domain_name: foo.ansible.vagrant
domain_admin_user: [email protected]
domain_admin_password: password123!
safe_mode_password: password123!
sysvol_path: D:\SYSVOL
database_path: D:\NTDS
log_path: D:\NTDS
register: dc_promotion
- name: Reboot after promotion
microsoft.ad.win_reboot:
when: dc_promotion.reboot_required