ansible.windows.win_group module – Add and remove local groups

Note

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

Synopsis

• Add and remove local groups.

• Adds and removes members of local groups.

• For non-Windows targets, please use the ansible.builtin.group module instead.

Parameters

Parameter	Comments
description string	Description of the group. Set to an empty string "" to unset the description.
members dictionary added in ansible.windows 2.7.0	The members of the group to set. The value is a dictionary that contains 3 keys, add, remove, or set. Each subkey value is a list of users or domain groups to add, remove, or set respectively. The members can either be the username in the form of SERVER\user, DOMAIN\user, .\user to represent a local user, a UPN user@DOMAIN.COM, or a security identifier S-1-5-..... A local group member cannot be another local group, it must be either a local user, domain user, or a domain group. The add and remove keys can be set together but set can only be set by itself.
add list / elements=string	The members to add to the group. This will add the members without removing any existing members not listed. Default: []
remove list / elements=string	The members to remove. This will remove the members from the group without removing any existing members not listed. Default: []
set list / elements=string	The members to set the group to. This will replace the existing membership with the users provided in this value. Can be set to [] to clear all members from the group.
name string / required	Name of the group.
state string	Create or remove the group. Choices: "absent" "present" ← (default)

See Also

See also

ansible.builtin.group

Add or remove groups.

community.windows.win_domain_group

Creates, modifies or removes domain groups.

Examples

- name: Create a new group
  ansible.windows.win_group:
    name: deploy
    description: Deploy Group
    state: present

- name: Remove a group
  ansible.windows.win_group:
    name: deploy
    state: absent

- name: Remove the group description
  ansible.windows.win_group:
    name: MyGroup
    description: ""
    state: present

- name: Add a user to a group
  ansible.windows.win_group:
    name: deploy
    members:
      add:
        - .\LocalUser1
        - LocalUser2
        - DOMAIN\User
        - [email protected]
        - S-1-5-0-10-204-0189-500
    state: present

- name: Remove a user from a group
  ansible.windows.win_group:
    name: deploy
    members:
      remove:
        - .\LocalUser1

- name: Set the members of a group
  ansible.windows.win_group:
    name: deploy
    members:
      set:
        - .\LocalUser1
        - LocalUser2
        - DOMAIN\User

- name: Remove all members of a group
  ansible.windows.win_group:
    name: deploy
    members:
      set: []

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
sid string	The Security Identifier (SID) of the group being managed. If a new group was created in check mode, the SID will be S-1-5-0000. When the group is not present, the SID will be None. Returned: always Sample: "S-1-5-21-2528685370-1724360342-165486190-1208"

Authors

• Chris Hoffman (@chrishoffman)

Collection links

• Issue Tracker
• Repository (Sources)