Skip to content
Documentation
State Modules
group

group

Manages a Unix group, optionally pinning its numeric GID. Idempotent: re-applying an unchanged declaration reports no change.

Category: System & core

States

StateMeaning
presentThe group exists with the declared GID (when gid is set); otherwise any existing GID is left untouched.
absentThe group does not exist; an existing group of that name is removed.

Parameters

ParameterTypeRequiredDescription
gidintNumeric GID to pin. When set, an existing group with a different GID is modified to match. Not allowed with state absent.
systemboolCreate as a system group (allocates from the system GID range). Honored only on group creation; not allowed with state absent. Default: false.

Examples

Ensure a group exists 

group:
  developers:
    state: present

Pin a numeric GID 

group:
  developers:
    state: present
    gid: 1500

System group, then removal of another 

group:
  app-runtime:
    state: present
    system: true
  legacy:
    state: absent

Notes

  • Linux has the full Check / Apply / Test pipeline. On macOS / BSD only the read-only lookup works; mutating applies return ErrUnsupportedOS.
  • On Linux the backend is auto-detected: shadow-utils (groupadd/groupmod/groupdel) when groupadd is present, otherwise BusyBox (addgroup/delgroup) on Alpine.
  • BusyBox ships no groupmod, so changing an existing group’s GID is unsupported on the BusyBox backend (ErrModUnsupported); creation and removal work.
  • gid and system cannot be set when state is absent.
  • Out of scope for v0.1: macOS via dscl, forced deletion of a user’s primary group, members: (use user.groups:), NIS/LDAP/SSSD mutations, and Windows.
filehostname