ansible.windows.win_domain_membership module – Manage domain/workgroup membership for a Windows host

Note

This module is part of the ansible.windows collection (version 2.5.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 ansible.windows.

To use it in a playbook, specify: ansible.windows.win_domain_membership.

DEPRECATED

Removed in:

version 3.0.0

Why:

This module has been moved into the microsoft.ad collection.

Alternative:

Use the microsoft.ad.membership module instead.

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.

Parameters

Parameter

Comments

dns_domain_name

string

When state is domain, the DNS name of the domain to which the targeted Windows host should be joined.

domain_admin_password

string

Password for the specified domain_admin_user.

domain_admin_user

string / required

Username of a domain admin for the target domain (required to join or leave the domain).

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.

hostname

string

The desired hostname for the Windows host.

state

string

Whether the target host should be a member of a domain or workgroup.

Choices:

  • "domain"

  • "workgroup"

workgroup_name

string

When state is workgroup, the name of the workgroup that the Windows host should be in.

See Also

See also

ansible.windows.win_domain

Ensures the existence of a Windows domain.

ansible.windows.win_domain_controller

Manage domain controller/member server state for a Windows host.

community.windows.win_domain_computer

Manage computers in Active Directory.

community.windows.win_domain_group

Creates, modifies or removes domain groups.

community.windows.win_domain_user

Manages Windows Active Directory user accounts.

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.

Examples

# host should be a member of domain ansible.vagrant; module will ensure the hostname is mydomainclient
# and will use the passed credentials to join domain if necessary.
# Ansible connection should use local credentials if possible.
# If a reboot is required, the second task will trigger one and wait until the host is available.
- name: Play to join the hosts to a domain
  hosts: winclient
  gather_facts: false
  tasks:
    - name: Join host to the ansible.vagrant domain
      ansible.windows.win_domain_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
      register: domain_state

    - name: Reboot host after domain join
      ansible.windows.win_reboot:
      when: domain_state.reboot_required

# Host should be in workgroup mywg- module will use the passed credentials to clean-unjoin domain if possible.
# Ansible connection should use local credentials if possible.
# The domain admin credentials can be sourced from a vault-encrypted variable
- name: Play to set the hosts workgroup
  hosts: winclient
  gather_facts: false
  tasks:
    - name: Set workgroup to mywg
      ansible.windows.win_domain_membership:
        workgroup_name: mywg
        domain_admin_user: '{{ win_domain_admin_user }}'
        domain_admin_password: '{{ win_domain_admin_password }}'
        state: workgroup

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

Status

  • This module will be removed in version 3.0.0. [deprecated]

  • For more information see DEPRECATED.

Authors

  • Matt Davis (@nitzmahone)