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 1.13.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.

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

The official documentation on the ansible.windows.win_domain module.

ansible.windows.win_domain_controller

The official documentation on the ansible.windows.win_domain_controller module.

community.windows.win_domain_computer

The official documentation on the community.windows.win_domain_computer module.

community.windows.win_domain_group

The official documentation on the community.windows.win_domain_group module.

community.windows.win_domain_user

The official documentation on the community.windows.win_domain_user module.

ansible.windows.win_group

The official documentation on the ansible.windows.win_group module.

ansible.windows.win_group_membership

The official documentation on the ansible.windows.win_group_membership module.

ansible.windows.win_user

The official documentation on the ansible.windows.win_user module.

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.
- hosts: winclient
  gather_facts: no
  tasks:
  - 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

  - 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
- hosts: winclient
  gather_facts: no
  tasks:
  - 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

Authors

  • Matt Davis (@nitzmahone)