You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

microsoft.ad.membership module – Manage domain/workgroup membership for a Windows host

Note

This module is part of the microsoft.ad collection (version 1.2.0).

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
Parameters
Attributes
See Also
Examples
Return Values

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
dns_domain_name string	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.
domain_admin_password string	Password for the specified `domain_admin_user`. This must be set unless offline_join_blob is specified.
domain_admin_user string	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.
domain_ou_path string	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.
hostname string	The desired hostname for the Windows host. This cannot be set when offline_join_blob is specified.
offline_join_blob string	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.
reboot boolean	If `true`, this will reboot the host if a reboot was required to configure the domain. If `false`, this will not reboot the host if a reboot was required and instead sets the reboot_required return value to `true`. If 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. This cannot be used with async mode. To use this parameter, ensure the fully qualified module name is used in the task or the collections keyword includes this collection. Choices: `false` ← (default) `true`
state string / required	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: `"domain"` `"workgroup"`
workgroup_name string	When state=workgroup, this is the name of the workgroup that the Windows host should be in.

Attributes 

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 `async` keyword
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 `run_once` is being used, variables used will be from the first available host 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
diff_mode	Support: full	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

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
reboot_required boolean	True if changes were made that require a reboot. Returned: always Sample: `true`

Authors

Matt Davis (@nitzmahone)
Jordan Borean (@jborean93)

Collection links

Issue Tracker Repository (Sources) Report an issue Communication

microsoft.ad.membership module – Manage domain/workgroup membership for a Windows host

Synopsis

Parameters

Attributes

See Also

Examples

Return Values