microsoft.ad.domain module – Ensures the existence of a Windows domain
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.
Synopsis
Ensure that the domain named by dns_domain_name exists and is reachable.
If the domain is not reachable, the domain is created in a new forest on the target Windows Server 2012+ host.
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 |
|---|---|
Whether to create a DNS delegation that references the new DNS server that you install along with the domain controller. 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 DNS name of the domain which should exist and be reachable or reside on the target Windows host. |
|
Specifies the domain functional level of the first domain in the creation of a new forest. 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 |
|
The NetBIOS name for the root domain in the new forest. For NetBIOS names to be valid for use with this parameter they must be single label names of 15 characters or less, if not it will fail. If this parameter is not set, then the default is automatically computed from the value of the domain_name parameter. |
|
Specifies the forest functional level for the new forest. The default forest functional level in Windows Server is typically the same as the version you are running. Current known modes are |
|
Whether to install the DNS service when creating the domain controller. Choices:
|
|
Specifies the fully qualified, non-UNC path to a directory on a fixed disk of the local computer where the log file for this operation is written. If not set then the default path is |
|
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. |
|
The path to a directory on a fixed disk of the Windows host where the Sysvol file 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
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.domain_child
Manage domain children in an existing Active Directory forest.
- microsoft.ad.domain_controller
Manage domain controller/member server state for a Windows host.
- 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.
- microsoft.ad.computer
Manage Active Directory computer objects.
- Migration guide
This module replaces
ansible.windows.win_domain. See the migration guide for details.- ansible.windows.win_domain
Ensures the existence of a Windows domain.
Examples
- name: Create new domain in a new forest on the target host and reboot
microsoft.ad.domain:
dns_domain_name: ansible.vagrant
safe_mode_password: password123!
reboot: true
- name: Create new Windows domain in a new forest with specific parameters and reboot in post task
microsoft.ad.domain:
create_dns_delegation: false
database_path: C:\Windows\NTDS
dns_domain_name: ansible.vagrant
domain_mode: Win2012R2
domain_netbios_name: ANSIBLE
forest_mode: Win2012R2
safe_mode_password: password123!
sysvol_path: C:\Windows\SYSVOL
register: domain_install
- name: Reboot host if install requires it
ansible.windows.win_reboot:
when: domain_install.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: |