Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 19. Managing host groups using Ansible playbooks

Organize IdM hosts into groups using Ansible to simplify the application of access control policies and other configurations.

19.1. Host groups in IdM
Copy link

Understand how IdM host groups centralize control over access policies and other management tasks for sets of hosts with common characteristics. For example, you can define host groups based on company departments, physical locations, or access control requirements.

A host group in IdM can include:

  • IdM servers and clients

  • Other IdM host groups

    Host groups created by default
    By default, the IdM server creates the host group ipaservers for all IdM server hosts.
    Direct and indirect group members
    Group attributes in IdM apply to both direct and indirect members: when host group B is a member of host group A, all members of host group B are considered indirect members of host group A.

Create Identity Management (IdM) host groups using Ansible to organize hosts for simplified access control and policy management.

Note

Without Ansible, host group entries are created in IdM using the ipa hostgroup-add command. The result of adding a host group to IdM is the state of the host group being present in IdM. Because of the Ansible reliance on idempotence, to add a host group to IdM using Ansible, you must create a playbook in which you define the state of the host group as present: state: present.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

Procedure

  1. Create an Ansible playbook file with the necessary host group information. To simplify the procedure, you can copy and modify the example in the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/user/ensure-hostgroup-is-present.yml file. 

    ---
- name: Playbook to handle hostgroups
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  # Ensure host-group databases is present
  - freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: databases
      state: present
    Copy to Clipboard Toggle word wrap

    In the playbook, state: present signifies a request to add the host group to IdM unless it already exists there.

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hostgroup-is-present.yml
    Copy to Clipboard Toggle word wrap

Verification

  1. Log into ipaserver as admin: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Request a Kerberos ticket for admin: 

    $ kinit admin
Password for admin@IDM.EXAMPLE.COM:
    Copy to Clipboard Toggle word wrap

  3. Display information about the host group whose presence in IdM you wanted to ensure: 

    $ ipa hostgroup-show databases
  Host-group: databases
    Copy to Clipboard Toggle word wrap

The databases host group exists in IdM.

Add hosts to Identity Management (IdM) host groups using Ansible to organize systems for access control and policy application.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • The hosts you want to reference in your Ansible playbook exist in IdM. For details, see Ensuring the presence of an IdM host entry using Ansible playbooks.
  • The host groups you reference from the Ansible playbook file have been added to IdM. For details, see Ensuring the presence of IdM host groups using Ansible playbooks.

Procedure

  1. Create an Ansible playbook file with the necessary host information:

    • Specify the name of the host group using the name variable of the freeipa.ansible_freeipa.ipahostgroup module.
    • Specify the name of the host with the host variable of the freeipa.ansible_freeipa.ipahostgroup module.

    To simplify the procedure, you can copy and modify the examples in the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-present-in-hostgroup.yml file: 

    ---
- name: Playbook to handle hostgroups
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  # Ensure host-group databases is present
  - freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: databases
      host:
      - db.idm.example.com
      action: member
    Copy to Clipboard Toggle word wrap

    This playbook adds the db.idm.example.com host to the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to add the databases group itself. Instead, only an attempt is made to add db.idm.example.com to databases.

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-present-in-hostgroup.yml
    Copy to Clipboard Toggle word wrap

Verification

  1. Log into ipaserver as admin: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Request a Kerberos ticket for admin: 

    $ kinit admin
Password for admin@IDM.EXAMPLE.COM:
    Copy to Clipboard Toggle word wrap

  3. Display information about a host group to see which hosts are present in it: 

    $ ipa hostgroup-show databases
  Host-group: databases
  Member hosts: db.idm.example.com
    Copy to Clipboard Toggle word wrap

The db.idm.example.com host is present as a member of the databases host group.

Nest host groups within parent groups in Identity Management (IdM) using Ansible to organize hosts into logical hierarchies.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • The host groups you reference from the Ansible playbook file exist in IdM. For details, see Ensuring the presence of IdM host groups using Ansible playbooks.

Procedure

  1. Create an Ansible playbook file with the necessary host group information:

    • To ensure that a nested host group A exists in a host group B: in the Ansible playbook, specify, among the variables of the freeipa.ansible_freeipa.ipahostgroup task, the name of the host group B using the name variable.
    • Specify the name of the nested hostgroup A with the hostgroup variable.

    To simplify this step, you can copy and modify the examples in the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-present-in-hostgroup.yml file: 

    ---
- name: Playbook to handle hostgroups
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  # Ensure hosts and hostgroups are present in existing databases hostgroup
  - freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: databases
      hostgroup:
      - mysql-server
      - oracle-server
      action: member
    Copy to Clipboard Toggle word wrap

    This Ansible playbook ensures the presence of the myqsl-server and oracle-server host groups in the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to add the databases group itself to IdM.

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-present-in-hostgroup.yml
    Copy to Clipboard Toggle word wrap

Verification

  1. Log into ipaserver as admin: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Request a Kerberos ticket for admin: 

    $ kinit admin
Password for admin@IDM.EXAMPLE.COM:
    Copy to Clipboard Toggle word wrap

  3. Display information about the host group in which nested host groups are present: 

    $ ipa hostgroup-show databases
  Host-group: databases
  Member hosts: db.idm.example.com
  Member host-groups: mysql-server, oracle-server
    Copy to Clipboard Toggle word wrap

The mysql-server and oracle-server host groups exist in the databases host group.

Delegate host group membership management to specific users or groups in Identity Management (IdM), allowing them to add and remove hosts.

Prerequisites

  • On the control node:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • You must have the name of the host or host group you are adding as member managers and the name of the host group you want them to manage.

Procedure

  1. Create an Ansible playbook file with the necessary host and host group member management information: 

    ---

- name: Playbook to handle host group membership management
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure member manager user example_member is present for group_name
      freeipa.ansible_freeipa.ipahostgroup:
        ipaadmin_password: "{{ ipaadmin_password }}"
        name: group_name
        membermanager_user: example_member

  - name: Ensure member manager group project_admins is present for group_name
      freeipa.ansible_freeipa.ipahostgroup:
        ipaadmin_password: "{{ ipaadmin_password }}"
        name: group_name
        membermanager_group: project_admins
    Copy to Clipboard Toggle word wrap

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-member-managers-host-groups.yml
    Copy to Clipboard Toggle word wrap

Verification

You can verify if the group_name group contains example_member and project_admins as member managers by using the ipa group-show command:

  1. Log into ipaserver as administrator: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Display information about testhostgroup: 

    ipaserver]$ ipa hostgroup-show group_name
  Host-group: group_name
  Member hosts: server.idm.example.com
  Member host-groups: testhostgroup2
  Membership managed by groups: project_admins
  Membership managed by users: example_member
    Copy to Clipboard Toggle word wrap

Remove hosts from Identity Management (IdM) host groups using Ansible when reorganizing group membership or decommissioning systems.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • The hosts you want to reference in your Ansible playbook exist in IdM. For details, see Ensuring the presence of an IdM host entry using Ansible playbooks.
  • The host groups you reference from the Ansible playbook file exist in IdM. For details, see Ensuring the presence of IdM host groups using Ansible playbooks.

Procedure

  1. Create an Ansible playbook file with the necessary host and host group information:

    • Specify the name of the host group using the name variable of the freeipa.ansible_freeipa.ipahostgroup module.
    • Specify the name of the host whose absence from the host group you want to ensure using the host variable of the freeipa.ansible_freeipa.ipahostgroup module.

    To simplify the procedure, you can copy and modify the examples in the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-absent-in-hostgroup.yml file: 

    ---
- name: Playbook to handle hostgroups
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  # Ensure host-group databases is absent
  - freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: databases
      host:
      - db.idm.example.com
      action: member
      state: absent
    Copy to Clipboard Toggle word wrap

    This playbook ensures the absence of the db.idm.example.com host from the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to remove the databases group itself.

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-absent-in-hostgroup.yml
    Copy to Clipboard Toggle word wrap

Verification

  1. Log into ipaserver as admin: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Request a Kerberos ticket for admin: 

    $ kinit admin
Password for admin@IDM.EXAMPLE.COM:
    Copy to Clipboard Toggle word wrap

  3. Display information about the host group and the hosts it contains: 

    $ ipa hostgroup-show databases
  Host-group: databases
  Member host-groups: mysql-server, oracle-server
    Copy to Clipboard Toggle word wrap

The db.idm.example.com host does not exist in the databases host group.

Remove nested host groups from parent groups in Identity Management (IdM) using Ansible when restructuring your host group hierarchy.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • The host groups you reference from the Ansible playbook file exist in IdM. For details, see Ensuring the presence of IdM host groups using Ansible playbooks.

Procedure

  1. Create an Ansible playbook file with the necessary host group information:

    • Specify, among the freeipa.ansible_freeipa.ipahostgroup variables, the name of the outer host group using the name variable.
    • Specify the name of the nested hostgroup with the hostgroup variable.

    To simplify this step, you can copy and modify the examples in the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-absent-in-hostgroup.yml file: 

    ---
- name: Playbook to handle hostgroups
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  # Ensure hosts and hostgroups are absent in existing databases hostgroup
  - freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: databases
      hostgroup:
      - mysql-server
      - oracle-server
      action: member
      state: absent
    Copy to Clipboard Toggle word wrap

    This playbook makes sure that the mysql-server and oracle-server host groups are absent from the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to ensure the databases group itself is deleted from IdM.

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-absent-in-hostgroup.yml
    Copy to Clipboard Toggle word wrap

Verification

  1. Log into ipaserver as admin: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Request a Kerberos ticket for admin: 

    $ kinit admin
Password for admin@IDM.EXAMPLE.COM:
    Copy to Clipboard Toggle word wrap

  3. Display information about the host group from which nested host groups should be absent: 

    $ ipa hostgroup-show databases
  Host-group: databases
    Copy to Clipboard Toggle word wrap

The output confirms that the mysql-server and oracle-server nested host groups are absent from the outer databases host group.

Delete Identity Management (IdM) host groups using Ansible when consolidating groups or removing obsolete groupings from your domain.

Note

Without Ansible, host group entries are removed from IdM using the ipa hostgroup-del command. The result of removing a host group from IdM is the state of the host group being absent from IdM. Because of the Ansible reliance on idempotence, to remove a host group from IdM using Ansible, you must create a playbook in which you define the state of the host group as absent: state: absent.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

Procedure

  1. Create an Ansible playbook file with the necessary host group information. To simplify this step, you can copy and modify the example in the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/user/ensure-hostgroup-is-absent.yml file. 

    ---
- name: Playbook to handle hostgroups
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - Ensure host-group databases is absent
    freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: databases
      state: absent
    Copy to Clipboard Toggle word wrap

    This playbook ensures the absence of the databases host group from IdM. The state: absent means a request to delete the host group from IdM unless it is already deleted.

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hostgroup-is-absent.yml
    Copy to Clipboard Toggle word wrap

Verification

  1. Log into ipaserver as admin: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Request a Kerberos ticket for admin: 

    $ kinit admin
Password for admin@IDM.EXAMPLE.COM:
    Copy to Clipboard Toggle word wrap

  3. Display information about the host group whose absence you ensured: 

    $ ipa hostgroup-show databases
ipa: ERROR: databases: host group not found
    Copy to Clipboard Toggle word wrap

The databases host group does not exist in IdM.

Remove member manager privileges from users or groups for Identity Management (IdM) host groups when revoking delegated management responsibilities.

Prerequisites

  • On the control node:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • You must have the name of the user or user group you are removing as member managers and the name of the host group they are managing.

Procedure

  1. Create an Ansible playbook file with the necessary host and host group member management information: 

    ---

- name: Playbook to handle host group membership management
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure member manager host and host group members are absent for group_name
    freeipa.ansible_freeipa.ipahostgroup:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: group_name
      membermanager_user: example_member
      membermanager_group: project_admins
      action: member
      state: absent
    Copy to Clipboard Toggle word wrap

  2. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-member-managers-host-groups-are-absent.yml
    Copy to Clipboard Toggle word wrap

Verification

You can verify if the group_name group does not contain example_member or project_admins as member managers by using the ipa group-show command:

  1. Log into ipaserver as administrator: 

    $ ssh admin@server.idm.example.com
Password:
[admin@server /]$
    Copy to Clipboard Toggle word wrap

  2. Display information about testhostgroup: 

    ipaserver]$ ipa hostgroup-show group_name
  Host-group: group_name
  Member hosts: server.idm.example.com
  Member host-groups: testhostgroup2
    Copy to Clipboard Toggle word wrap
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top