Chapter 18. Managing host groups using Ansible playbooks
To learn more about host groups in Identity Management (IdM) and using Ansible to perform operations involving host groups in Identity Management (IdM), see the following:
- Host groups in IdM
- Ensuring the presence of IdM host groups
- Ensuring the presence of hosts in IdM host groups
- Nesting IdM host groups
- Ensuring the presence of member managers in IdM host groups
- Ensuring the absence of hosts from IdM host groups
- Ensuring the absence of nested host groups from IdM host groups
- Ensuring the absence of member managers from IdM host groups
18.1. Host groups in IdM
IdM host groups can be used to centralize control over important management tasks, particularly access control.
Definition of host groups
A host group is an entity that contains a set of IdM hosts with common access control rules and other 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.
18.2. Ensuring the presence of IdM host groups using Ansible playbooks
Follow this procedure to ensure the presence of host groups in Identity Management (IdM) using Ansible playbooks.
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 know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it with the list of IdM servers to target:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary host group information. For example, to ensure the presence of a host group named databases, specify
name: databases
in the- ipahostgroup
task. To simplify this step, you can copy and modify the example in the/usr/share/doc/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 - ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: databases state: present
In the playbook, state: present signifies a request to add the host group to IdM unless it already exists there.
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
Verification
Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
Display information about the host group whose presence in IdM you wanted to ensure:
$ ipa hostgroup-show databases Host-group: databases
The databases host group exists in IdM.
18.3. Ensuring the presence of hosts in IdM host groups using Ansible playbooks
Follow this procedure to ensure the presence of hosts in host groups in Identity Management (IdM) using Ansible playbooks.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
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
Create an inventory file, for example
inventory.file
, and defineipaserver
in it with the list of IdM servers to target:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary host information. Specify the name of the host group using the
name
parameter of theipahostgroup
variable. Specify the name of the host with thehost
parameter of theipahostgroup
variable. To simplify this step, you can copy and modify the examples in the/usr/share/doc/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 - ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: databases host: - db.idm.example.com action: member
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.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
Verification
Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
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
The db.idm.example.com host is present as a member of the databases host group.
18.4. Nesting IdM host groups using Ansible playbooks
Follow this procedure to ensure the presence of nested host groups in Identity Management (IdM) host groups using Ansible playbooks.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
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
Create an inventory file, for example
inventory.file
, and defineipaserver
in it with the list of IdM servers to target:[ipaserver] server.idm.example.com
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
- ipahostgroup
variables, the name of the host group B using thename
variable. Specify the name of the nested hostgroup A with thehostgroup
variable. To simplify this step, you can copy and modify the examples in the/usr/share/doc/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 - ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: databases hostgroup: - mysql-server - oracle-server action: member
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.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
Verification
Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
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
The mysql-server and oracle-server host groups exist in the databases host group.
18.5. Ensuring the presence of member managers in IDM host groups using Ansible Playbooks
The following procedure describes ensuring the presence of member managers in IdM hosts and host groups using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
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
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
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 ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: group_name membermanager_user: example_member - name: Ensure member manager group project_admins is present for group_name ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: group_name membermanager_group: project_admins
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
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:
Log into
ipaserver
as administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
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
Additional resources
-
See
ipa hostgroup-add-member-manager --help
. -
See the
ipa
man page on your system.
18.6. Ensuring the absence of hosts from IdM host groups using Ansible playbooks
Follow this procedure to ensure the absence of hosts from host groups in Identity Management (IdM) using Ansible playbooks.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
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
Create an inventory file, for example
inventory.file
, and defineipaserver
in it with the list of IdM servers to target:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary host and host group information. Specify the name of the host group using the
name
parameter of theipahostgroup
variable. Specify the name of the host whose absence from the host group you want to ensure using thehost
parameter of theipahostgroup
variable. To simplify this step, you can copy and modify the examples in the/usr/share/doc/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 - ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: databases host: - db.idm.example.com action: member state: absent
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.
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
Verification
Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
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
The db.idm.example.com host does not exist in the databases host group.
18.7. Ensuring the absence of nested host groups from IdM host groups using Ansible playbooks
Follow this procedure to ensure the absence of nested host groups from outer host groups in Identity Management (IdM) using Ansible playbooks.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
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
Create an inventory file, for example
inventory.file
, and defineipaserver
in it with the list of IdM servers to target:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary host group information. Specify, among the
- ipahostgroup
variables, the name of the outer host group using thename
variable. Specify the name of the nested hostgroup with thehostgroup
variable. To simplify this step, you can copy and modify the examples in the/usr/share/doc/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 - ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: databases hostgroup: - mysql-server - oracle-server action: member state: absent
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.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
Verification
Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
Display information about the host group from which nested host groups should be absent:
$ ipa hostgroup-show databases Host-group: databases
The output confirms that the mysql-server and oracle-server nested host groups are absent from the outer databases host group.
18.8. Ensuring the absence of IdM host groups using Ansible playbooks
Follow this procedure to ensure the absence of host groups in Identity Management (IdM) using Ansible playbooks.
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 know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it with the list of IdM servers to target:[ipaserver] server.idm.example.com
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/doc/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 ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: databases state: absent
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.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
Verification
Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
Display information about the host group whose absence you ensured:
$ ipa hostgroup-show databases ipa: ERROR: databases: host group not found
The databases host group does not exist in IdM.
18.9. Ensuring the absence of member managers from IdM host groups using Ansible playbooks
The following procedure describes ensuring the absence of member managers in IdM hosts and host groups using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - 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
.
-
The target node, that is the node on which the
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
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
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 ipahostgroup: ipaadmin_password: "{{ ipaadmin_password }}" name: group_name membermanager_user: example_member membermanager_group: project_admins action: member state: absent
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
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:
Log into
ipaserver
as administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Display information about testhostgroup:
ipaserver]$ ipa hostgroup-show group_name Host-group: group_name Member hosts: server.idm.example.com Member host-groups: testhostgroup2
Additional resources
-
See
ipa hostgroup-add-member-manager --help
. -
See the
ipa
man page on your system.