Chapter 23. Installing an Identity Management replica using an Ansible playbook
23.1. Ansible and its advantages for installing IdM
Ansible is an automation tool used to configure systems, deploy software, and perform rolling updates. Ansible includes support for Identity Management (IdM), and you can use Ansible modules to automate installation tasks such as the setup of an IdM server, replica, client, or an entire IdM topology.
Advantages of using Ansible to install IdM
The following list presents advantages of installing Identity Management using Ansible in contrast to manual installation.
- You do not need to log into the managed node.
- You do not need to configure settings on each host to be deployed individually. Instead, you can have one inventory file to deploy a complete cluster.
- You can reuse an inventory file later for management tasks, for example to add users and hosts. You can reuse an inventory file even for such tasks as are not related to IdM.
23.2. IdM replica installation using an Ansible playbook
The following sections describe how to configure a system as an IdM replica by using Ansible. Configuring a system as an IdM replica enrolls it into an IdM domain and enables the system to use IdM services on IdM servers in the domain.
The deployment is managed by the ipareplica
Ansible role. The role can use the autodiscovery mode for identifying the IdM servers, domain and other settings. However, if you deploy multiple replicas in a tier-like model, with different groups of replicas being deployed at different times, you must defined specific servers or replicas for each group.
Before installing an IdM replica using Ansible, ensure that you understand Ansible and IdM concepts. Ensure that you understand the following terms that are used in this chapter:
- Ansible roles
- Ansible nodes
- Ansible inventory
- Ansible tasks
- Ansible modules
- Ansible plays and playbooks
Overview
The installation consists of the following parts:
23.3. Installing the ansible-freeipa package
Prerequisites
On the managed node:
- Ensure that the managed node is a Red Hat Enterprise Linux 8 system with a static IP address and a working package manager.
On the controller:
- Ensure that the controller is a Red Hat Enterprise Linux system with a valid subscription. If this is not the case, see the official Ansible documentation Installation guide for alternative installation instructions.
-
Ensure that you can reach the managed node over the
SSH
protocol from the controller. Check that the managed node is listed in the/root/.ssh/known_hosts
file of the controller.
Procedure
Run the following procedure on the Ansible controller.
Enable the required repository:
# subscription-manager repos --enable ansible-2.8-for-rhel-8-x86_64-rpms
Install Ansible:
# yum install ansible
Install the IdM Ansible roles:
# yum install ansible-freeipa
The roles are installed to the
/usr/share/ansible/roles/
directory.
23.4. Ansible roles location in the file system
By default the ansible-freeipa
roles are installed to the /usr/share/ansible/roles/
directory. The structure of the ansible-freeipa
package is as follows:
The
/usr/share/ansible/roles/
directory stores theipaserver
,ipareplica
, andipaclient
roles on the Ansible controller. Each role directory stores examples, a basic overview, the licence and documentation about the role in a README.md Markdown file.[root@server]# ls -1 /usr/share/ansible/roles/ ipaclient ipareplica ipaserver
The
/usr/share/doc/ansible-freeipa/
directory stores the documentation about individual roles and the topology in README.md Markdown files. It also stores theplaybooks/
subdirectory (see below).[root@server]# ls -1 /usr/share/doc/ansible-freeipa/ playbooks README-client.md README.md README-replica.md README-server.md README-topology.md
The
/usr/share/doc/ansible-freeipa/playbooks/
directory stores the example playbooks:[root@server]# ls -1 /usr/share/doc/ansible-freeipa/playbooks/ install-client.yml install-cluster.yml install-replica.yml install-server.yml uninstall-client.yml uninstall-cluster.yml uninstall-replica.yml uninstall-server.yml
23.5. Setting the parameters of the IdM replica deployment
Before you deploy a target host as an IdM replica, configure the following settings:
23.5.1. Specifying the base, server and client variables for installing the IdM replica
Complete this procedure to configure the inventory file for installing an IdM replica.
Procedure
Open the inventory file for editing. Specify the fully-qualified domain names (
FQDN
) of the hosts to become IdM replicas. TheFQDNs
must be valid DNS names:- Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
The host name must be all lower-case.
Example of a simple inventory hosts file with only the replicas' FQDN defined
[ipareplicas] replica1.idm.example.com replica2.idm.example.com replica3.idm.example.com [...]
If the IdM server is already deployed and the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values.
Optionally, provide additional information in the inventory file based on which of the following scenarios is closest to yours:
Scenario 1
If you want to avoid autodiscovery and have all replicas listed in the
[ipareplicas]
section use a specific IdM server, set the server in the[ipaservers]
section of the inventory file.Example inventory hosts file with the FQDN of the IdM server and replicas defined
[ipaservers] server.idm.example.com [ipareplicas] replica1.idm.example.com replica2.idm.example.com replica3.idm.example.com [...]
Scenario 2
Alternatively, if you want to avoid autodiscovery but want to deploy specific replicas with specific servers, set the servers for specific replicas individually in the
[ipareplicas]
section in the inventory file.Example inventory file with a specific IdM server defined for a specific replica
[ipaservers] server.idm.example.com replica1.idm.example.com [ipareplicas] replica2.idm.example.com replica3.idm.example.com ipareplica_servers=replica1.idm.example.com
In the example above,
replica3.idm.example.com
uses the already deployedreplica1.idm.example.com
as its replication source.Scenario 3
If you are deploying several replicas in one batch and time is a concern to you, multitier replica deployment can be useful for you. Define specific groups of replicas in the inventory file, for example
[ipareplicas_tier1]
and[ipareplicas_tier2]
, and design separate plays for each group in theinstall-replica.yml
playbook.Example inventory file with replica tiers defined
[ipaservers] server.idm.example.com [ipareplicas_tier1] replica1.idm.example.com [ipareplicas_tier2] replica2.idm.example.com \ ipareplica_servers=replica1.idm.example.com,server.idm.example.com
The first entry in
ipareplica_servers
will be used. The second entry will be used as a fallback option. When using multiple tiers for deploying IdM replicas, you must have separate tasks in the playbook to first deploy replicas from tier1 and then replicas from tier2:Example of a playbook file with different plays for different replica groups
--- - name: Playbook to configure IPA replicas (tier1) hosts: ipareplicas_tier1 become: true roles: - role: ipareplica state: present - name: Playbook to configure IPA replicas (tier2) hosts: ipareplicas_tier2 become: true roles: - role: ipareplica state: present
23.5.2. Specifying the credentials for installing the IdM replica using an Ansible playbook
Complete this procedure to configure the authorization for installing the IdM replica.
Procedure
Specify the password of a user authorized to deploy replicas, for example the IdM
admin
.Red Hat recommends using the Ansible Vault to store the password, and referencing the Vault file from the playbook file, for example
install-replica.yml
:Example playbook file using principal from inventory file and password from an Ansible Vault file
- name: Playbook to configure IPA replicas hosts: ipareplicas become: true vars_files: -
playbook_sensitive_data.yml
roles: - role: ipareplica state: presentFor details how to use Ansible Vault, see the official Ansible Vault documentation.
Less securely, provide the credentials of
admin
directly in the inventory file. Use theipaadmin_password
option in the[ipareplicas:vars]
section of the inventory file. The inventory file and theinstall-replica.yml
playbook file can then look as follows:Example inventory hosts.replica file
[...] [ipareplicas:vars] ipaadmin_password=Secret123
Example playbook using principal and password from inventory file
- name: Playbook to configure IPA replicas hosts: ipareplicas become: true roles: - role: ipareplica state: present
Alternatively but also less securely, provide the credentials of another user authorized to deploy a replica directly in the inventory file. To specify a different authorized user, use the
ipaadmin_principal
option for the user name, and theipaadmin_password
option for the password. The inventory file and theinstall-replica.yml
playbook file can then look as follows:Example inventory hosts.replica file
[...] [ipareplicas:vars] ipaadmin_principal=my_admin ipaadmin_password=my_admin_secret123
Example playbook using principal and password from inventory file
- name: Playbook to configure IPA replicas hosts: ipareplicas become: true roles: - role: ipareplica state: present
Additional resources
-
For details on the options accepted by the
ipareplica
Ansible role, see the/usr/share/ansible/roles/ipareplica/README.md
Markdown file.
23.6. Deploying an IdM replica using an Ansible playbook
Complete this procedure to use an Ansible playbook to deploy an IdM replica.
Procedure
To install an IdM replica using an Ansible playbook, use the
ansible-playbook
command with the name of the playbook file, for exampleinstall-replica.yml
. Specify the inventory file with the-i
option:$ ansible-playbook -v -i <path_to_inventory_directory>/hosts.replica <path_to_playbooks_directory>/install-replica.yml
Specify the level of verbosity by using the
-v
,-vv
or-vvv
option.Ansible informs you about the execution of the Ansible playbook script. The following output shows that the script has run successfully as 0 tasks have failed:
PLAY RECAP replica.idm.example.com : ok=18 changed=10 unreachable=0 failed=0 skipped=21 rescued=0 ignored=0
You have now installed an IdM replica.