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 |
---|---|
When |
|
Password for the specified |
|
Username of a domain admin for the target domain (required to join or leave the domain). |
|
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. |
|
The desired hostname for the Windows host. |
|
Whether the target host should be a member of a domain or workgroup. Choices:
|
|
When |
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 |
---|---|
True if changes were made that require a reboot. Returned: always Sample: |