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

Note

This module is part of the microsoft.ad collection (version 1.4.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

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

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

reboot_required

boolean

True if changes were made that require a reboot.

Returned: always

Sample: true

Authors

  • Matt Davis (@nitzmahone)

  • Jordan Borean (@jborean93)