microsoft.ad.membership module – Manage domain/workgroup membership 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.membership.
Synopsis
Manages domain membership or workgroup membership for a Windows host. Also supports hostname changes.
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 |
|---|---|
When state=domain, this is the DNS name of the domain to which the targeted Windows host should be joined. This cannot be set when offline_join_blob is specified. |
|
Password for the specified This must be set unless offline_join_blob is specified. |
|
Username of a domain admin for the target domain (required to join or leave the domain). This must be set unless offline_join_blob is specified. |
|
The desired OU path for adding the computer object. This is only used when adding the target host to a domain, if it is already a member then it is ignored. This cannot be set when offline_join_blob is specified. |
|
Specifies the domain controller to use when joining the domain. |
|
The desired hostname for the Windows host. This cannot be set when offline_join_blob is specified. |
|
The base64 string of the domain offline join blob to use when joining the host to a domain. This blob can been generated by the microsoft.ad.offline_join module. This is mutually exclusive with domain_admin_user, dns_domain_name, and domain_ou_path. It also cannot be used with hostname. |
|
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: |
|
Whether the target host should be a member of a domain or workgroup. When state=domain, dns_domain_name, domain_admin_user, and domain_admin_password or offline_join_blob must be set. When state=workgroup, workgroup_name must be set. Choices:
|
|
When state=workgroup, this is the name of the workgroup that the Windows host should be in. |
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: full |
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 and changing from a domain to workgroup, the connection account must be a local user that can connect to the host after it has unjoined the domain. 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
Ensures the existence of a Windows domain.
- microsoft.ad.domain_controller
Manage domain controller/member server state for a Windows host.
- microsoft.ad.group
Manage Active Directory group objects.
- microsoft.ad.offline_join
Get the Offline Domain Join BLOB.
- microsoft.ad.user
Manage Active Directory users.
- microsoft.ad.computer
Manage Active Directory computer objects.
- ansible.windows.win_group
Add and remove local groups.
- ansible.windows.win_group_membership
Manage Windows local group membership.
- ansible.windows.win_user
Manages local Windows user accounts.
- Migration guide
This module replaces
ansible.windows.win_domain_membership. See the migration guide for details.- ansible.windows.win_domain_membership
Manage domain/workgroup membership for a Windows host.
Examples
- name: join host to ansible.vagrant with automatic reboot
microsoft.ad.membership:
dns_domain_name: ansible.vagrant
hostname: mydomainclient
domain_admin_user: [email protected]
domain_admin_password: password123!
domain_ou_path: "OU=Windows,OU=Servers,DC=ansible,DC=vagrant"
state: domain
reboot: true
- name: join host to workgroup with manual reboot in later task
microsoft.ad.membership:
workgroup_name: mywg
domain_admin_user: '{{ win_domain_admin_user }}'
domain_admin_password: '{{ win_domain_admin_password }}'
state: workgroup
register: workgroup_res
- name: reboot host after joining workgroup
ansible.windows.win_reboot:
when: workgroup_res.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: |