Skip to content

group_by

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version 0.9.

Synopsis

  • Use facts to create ad-hoc groups that can be used later in a playbook.
  • This module is also supported for Windows targets.

Parameters

Parameter Defaults / Choices Comments
key
str
required		 The variables whose values will be used as groups.
parents
list / elements=str		 Default: all
 The list of the parent groups.
Version Added: 2.4

Notes

Note

  • Spaces in group names are converted to dashes '-'.
  • Though this module does not change the remote host, we do provide 'changed' status as it can be useful for those trying to track inventory changes.

Examples

- name: Create groups based on the machine architecture
  ansible.builtin.group_by:
    key: machine_{{ ansible_machine }}

- name: Create groups like 'virt_kvm_host'
  ansible.builtin.group_by:
    key: virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }}

- name: Create nested groups
  ansible.builtin.group_by:
    key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
    parents:
      - el{{ ansible_distribution_major_version }}

- name: Add all active hosts to a static group
  ansible.builtin.group_by:
    key: done

Authors

  • Jeroen Hoekx (@jhoekx)