# Copyright (c) 2022 Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION:
  module: membership
  short_description: Manage domain/workgroup membership for a Windows host
  description:
    - Manages domain membership or workgroup membership for a Windows host. Also
      supports hostname changes.
    - This module may require subsequent use of the
      M(ansible.windows.win_reboot) action if changes are made.
  options:
    dns_domain_name:
      description:
        - When I(state=domain), this is the DNS name of the domain to which the
          targeted Windows host should be joined.
        - This cannot be set when I(offline_join_blob) is specified.
      type: str
    domain_admin_user:
      description:
        - Username of a domain admin for the target domain (required to join or
          leave the domain).
        - This must be set unless I(offline_join_blob) is specified.
      type: str
    domain_admin_password:
      description:
        - Password for the specified C(domain_admin_user).
        - This must be set unless I(offline_join_blob) is specified.
      type: str
    domain_ou_path:
      description:
        - 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 I(offline_join_blob) is specified.
      type: str
    domain_server:
      description:
        - Specifies the domain controller to use when joining the domain.
      type: str
      version_added: 1.7.0
    hostname:
      description:
        - The desired hostname for the Windows host.
        - This cannot be set when I(offline_join_blob) is specified.
      type: str
    offline_join_blob:
      description:
        - 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
          M(microsoft.ad.offline_join) module.
        - This is mutually exclusive with I(domain_admin_user),
          I(dns_domain_name), and I(domain_ou_path).
        - It also cannot be used with I(hostname).
      type: str
    state:
      description:
        - Whether the target host should be a member of a domain or workgroup.
        - When I(state=domain), I(dns_domain_name), I(domain_admin_user), and
          I(domain_admin_password) or I(offline_join_blob) must be set.
        - When I(state=workgroup), I(workgroup_name) must be set.
      choices:
        - domain
        - workgroup
      required: true
      type: str
    workgroup_name:
      description:
        - When I(state=workgroup), this is the name of the workgroup that the
          Windows host should be in.
      type: str
  notes:
    - This module must be run on a Windows target host.
    - If using I(reboot=true) and 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. Also ensure the fully qualified module name is
      used in the task or the I(collections) keyword includes this collection.
  extends_documentation_fragment:
    - ansible.builtin.action_common_attributes
    - ansible.builtin.action_common_attributes.flow
    - microsoft.ad.action_reboot
  attributes:
    check_mode:
      support: full
    diff_mode:
      support: full
    platform:
      platforms:
        - windows
    action:
      support: full
    async:
      support: partial
      details: Supported for all scenarios except with I(reboot=True).
    bypass_host_loop:
      support: none
  seealso:
    - module: microsoft.ad.domain
    - module: microsoft.ad.domain_controller
    - module: microsoft.ad.group
    - module: microsoft.ad.offline_join
    - module: microsoft.ad.user
    - module: microsoft.ad.computer
    - module: ansible.windows.win_group
    - module: ansible.windows.win_group_membership
    - module: ansible.windows.win_user
    - ref: Migration guide <ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_membership>
      description: This module replaces C(ansible.windows.win_domain_membership). See the migration guide for details.
    - module: ansible.windows.win_domain_membership
  author:
    - Matt Davis (@nitzmahone)
    - Jordan Borean (@jborean93)

EXAMPLES: |
  - name: join host to ansible.vagrant with automatic reboot
    microsoft.ad.membership:
      dns_domain_name: ansible.vagrant
      hostname: mydomainclient
      domain_admin_user: testguy@ansible.vagrant
      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:
  reboot_required:
    description: True if changes were made that require a reboot.
    returned: always
    type: bool
    sample: true
