Ansible group Module: Create & Manage Linux Groups (ansible.builtin.group)

By Luca Berton · Published 2024-01-01 · Category: troubleshooting

How to create and manage Linux groups with Ansible group module (ansible.builtin.group). Add groups, set GID, manage system groups.

Ansible group Module: Create & Manage Linux Groups (ansible.builtin.group)

How to create a group in Linux with Ansible?

Ansible creates a group

> ansible.builtin.group Add or remove groups

Today we're talking about the Ansible module group. The full name is ansible.builtin.group, which means that is part of the collection of modules "builtin" with Ansible and shipped with it. It's a module pretty stable and out for years. It adds or removes groups. It supports a huge variety of Linux distributions and macOS. It relies on three Linux commands: groupadd, groupdel and groupmod. For Windows, use the ansible.windows.win_group module instead.

Parameters

name string - group name
state string - present/absent
system boolean - yes/no
gid integer - GID to set for the group
local string - "local" command alternatives

This module has some parameters to perform some tasks. The only required is "name", which is the group name. The "state" parameter allows us to create or delete a group, in our use case the default it's already set to "present" to create a group. The "system" parameter allows for the creation of a system group, default it's not. You could specify the "GID", the group identifier, in using the "gid" parameter. The "local" parameter allows using the "local" command alternatives on platforms that implement it if you have a central authentication system.

## Playbook Let's jump in a real-life Ansible Playbook to create a group.

code

create_group.yml

---
- name: group module Playbook
  hosts: all
  become: true
  vars:
    mygroup: "example"
  tasks:
    - name: create group
      ansible.builtin.group:
        name: "{{ mygroup }}"
        state: present

execution

$ ansible-playbook group/create.yml
PLAY [group module Playbook] **************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [create group] *******************************************************************************
changed: [demo.example.com]
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

verification

$ ssh devops@demo.example.com
$ sudo su
# getent group | grep example

example:x:1001:

code with ❤️ in GitHub

Conclusion

Now you know how to create a group in Linux with Ansible.

Create Groups

Basic group

- name: Create developers group
  ansible.builtin.group:
    name: developers
    state: present
  become: true

With specific GID

- name: Create group with GID
  ansible.builtin.group:
    name: appteam
    gid: 1500
    state: present
  become: true

System group

- name: Create system group
  ansible.builtin.group:
    name: myapp
    system: true
    state: present
  become: true

Create Group and Add Users

- name: Create project group
  ansible.builtin.group:
    name: project-alpha
    state: present
  become: true

- name: Add users to group
  ansible.builtin.user:
    name: "{{ item }}"
    groups: project-alpha
    append: true  # Don't remove from other groups
  loop:
    - alice
    - bob
    - charlie
  become: true

Multiple Groups

- name: Create all application groups
  ansible.builtin.group:
    name: "{{ item.name }}"
    gid: "{{ item.gid | default(omit) }}"
    state: present
  loop:
    - { name: developers, gid: 1500 }
    - { name: operations, gid: 1501 }
    - { name: dba, gid: 1502 }
    - { name: security }
  become: true

Full User/Group Setup Pattern

---
- name: Setup users and groups
  hosts: all
  become: true
  vars:
    groups:
      - { name: developers, gid: 1500 }
      - { name: ops, gid: 1501 }
    users:
      - { name: alice, groups: "developers,ops" }
      - { name: bob, groups: "developers" }

  tasks:
    - name: Create groups
      ansible.builtin.group:
        name: "{{ item.name }}"
        gid: "{{ item.gid }}"
      loop: "{{ groups }}"

    - name: Create users
      ansible.builtin.user:
        name: "{{ item.name }}"
        groups: "{{ item.groups }}"
        append: true
      loop: "{{ users }}"

Key Parameters

Parameter	Description
`name`	Group name (required)
`gid`	Group ID number
`state`	`present` or `absent`
`system`	Create as system group
`local`	Use local commands (ignore LDAP/NIS)

Windows Groups

- name: Create Windows local group
  ansible.windows.win_group:
    name: AppAdmins
    description: Application administrators
    state: present

FAQ

How do I check if a group exists?

- ansible.builtin.getent:
    database: group
    key: developers
  register: group_check
  failed_when: false

What's the difference between `group` and `user` modules for groups?

group module: Creates/deletes the group itself
user module: Adds users TO groups (via groups parameter)

Does creating a group that already exists cause changes?

No - the task shows ok if the group already exists with matching properties. If GID differs, it updates.

Create a Group

- name: Create application group
  ansible.builtin.group:
    name: appgroup
    state: present
  become: true

With Specific GID

- group:
    name: myapp
    gid: 1500
    state: present
  become: true

System Group

- group:
    name: myservice
    system: true
    state: present
  become: true

Create Multiple Groups

- group:
    name: "{{ item.name }}"
    gid: "{{ item.gid | default(omit) }}"
    system: "{{ item.system | default(false) }}"
  loop:
    - { name: webteam, gid: 2001 }
    - { name: dbteam, gid: 2002 }
    - { name: devops, gid: 2003 }
    - { name: monitoring, system: true }
  become: true

Group + User Together

- name: Create app group
  group:
    name: myapp
    gid: 1500
  become: true

- name: Create app user in group
  user:
    name: myapp
    group: myapp
    system: true
    shell: /sbin/nologin
    home: /opt/myapp
    create_home: true
  become: true

Add User to Multiple Groups

- user:
    name: deploy
    groups:
      - docker
      - sudo
      - webteam
    append: true  # Don't remove from existing groups
  become: true

Onboarding Pattern

---
- name: Onboard new team member
  hosts: all
  become: true
  vars:
    new_user: alice
    user_groups: [docker, devops, sudo]
  tasks:
    - name: Ensure groups exist
      group:
        name: "{{ item }}"
        state: present
      loop: "{{ user_groups }}"

    - name: Create user
      user:
        name: "{{ new_user }}"
        groups: "{{ user_groups }}"
        shell: /bin/bash
        create_home: true

    - name: Add SSH key
      authorized_key:
        user: "{{ new_user }}"
        key: "{{ lookup('file', 'keys/' + new_user + '.pub') }}"

Check Group Membership

- command: "getent group {{ group_name }}"
  register: group_info
  changed_when: false

- debug:
    msg: "Members of {{ group_name }}: {{ group_info.stdout.split(':')[3] }}"

group Module Parameters

Parameter	Description
`name`	Group name (required)
`state`	`present` or `absent`
`gid`	Group ID number
`system`	Create system group (low GID)
`force`	Force actions
`local`	Use local commands only
`non_unique`	Allow duplicate GIDs

FAQ

What GID range is used?

Regular groups: typically 1000-65533. System groups: typically 100-999. Controlled by /etc/login.defs.

Can I rename a group?

The group module doesn't support renaming. Create new group, move users, delete old group.

Windows equivalent?

- ansible.windows.win_group:
    name: MyAppUsers
    state: present

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton