Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 23. Installing an Identity Management replica using an Ansible playbook

23.1. 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.

Note

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:

Prerequisites

  • You have installed the ansible-freeipa package on the Ansible control node.

23.2. Setting the parameters of the IdM replica deployment

Before you deploy a target host as an IdM replica, configure the following settings:

23.2.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

  1. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the hosts to become IdM replicas. The FQDNs 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.

  2. 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 deployed replica1.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 the install-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

    • Scenario 4

      If you want the replica to use a specified firewalld zone instead of the default one, you can specify it in the inventory file. This can be useful, for example, when you want to use an internal firewalld zone for your IdM installation instead of a public zone that is set as default.

      If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

      Important

      The specified firewalld zone must exist and be permanent.

      Example of a simple inventory hosts file with a custom firewalld zone

      [ipaservers]
      server.idm.example.com
      
      [ipareplicas]
      replica1.idm.example.com
      replica2.idm.example.com
      replica3.idm.example.com
      [...]
      
      [ipareplicas:vars]
      ipareplica_firewalld_zone=custom zone

23.2.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

  1. 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: present

      For 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 the ipaadmin_password option in the [ipareplicas:vars] section of the inventory file. The inventory file and the install-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 the ipaadmin_password option for the password. The inventory file and the install-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.3. 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 example install-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.