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

Note

This module is part of the ansible.windows collection (version 3.0.0).

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

The official documentation on the ansible.builtin.group module.

community.windows.win_domain_group

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

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
        - user@DOMAIN.COM
        - 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)