ansible.windows.win_domain_membership – Manage domain/workgroup membership for a Windows host
Note
This plugin is part of the ansible.windows collection (version 1.7.3).
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 | Choices/Defaults | 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. |
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 | Returned | Description |
---|---|---|
reboot_required boolean | always | True if changes were made that require a reboot. Sample: True |
Authors
- Matt Davis (@nitzmahone)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_domain_membership_module.html