Chapter 6. Upgrading large deployments by using Ansible roles

Procedure

1. Create a playbook file, for example ~/analysis.yml, with the following content:

   ---
   - name: RHEL pre-upgrade analysis
     hosts: managed-node-01.example.com
   
     tasks:
       - name: Generate pre-upgrade analysis report
         ansible.builtin.import_role:
           name: redhat.leapp.analysis
         vars:
           leapp_upgrade_type: satellite
           leapp_satellite_organization: <satellite_org>
           leapp_satellite_activation_key_post_analysis: <activation_key_post_analysis>
           leapp_satellite_activation_key: <activation_key>

   The settings specified in the example playbook include the following:

   leapp_upgrade_type: <upgrade_type>

   Optional: The type of upgrade being performed. The default value is cdn, which must be used for hosts registered with Red Hat CDN. Set to satellite for hosts registered with Satellite, rhui for hosts using RHUI repositories, and custom for custom repositories. Note that the playbook example above uses Satellite, not the default CDN.

   leapp_satellite_organization: <organization>

   Optional: Organization used in Satellite definition. Use only if upgrading by using Satellite. You can omit this variable if the system is registered with an activation key for a content view that includes both the current RHEL version and the next version repositories.

   leapp_satellite_activation_key_post_analysis: <activation_key_post_analysis>

   Optional: Activation key for the current RHEL version content view to register to after analysis. Use only if upgrading by using Satellite. You can omit this variable if the system is registered with an activation key for the content view, including both the current RHEL version and the next version.

   leapp_satellite_activation_key: <activation_key>

   Optional: Activation key for the content view, including both the current RHEL version and the next version. Use only if upgrading by using Satellite. You can omit this variable if the system is registered with an activation key for the content view, including both the current RHEL version and the next version.

   leapp_preupg_opts: <options>

   Optional: List of command line options to run with the pre-upgrade command, namely:

   • --target <target_os_version>
   • --enablerepo <repository_id> if you are upgrading with custom repositories
   • --no-rhsm if you are upgrading with custom repositories
   • --channel <channel> if you have an EUS or AUS subscription

   leapp_answerfile: <answerfile>

   Optional: In certain system configurations, the pre-upgrade report requires you to respond to certain true or false questions. This variable sets the true or false answer to the designated question.

   For details about all variables that can be used in the playbook, see the /usr/share/ansible/collections/ansible_collections/redhat/leapp/roles/analysis/README.md file on the control node.

   Note that if you upgrade systems that run different RHEL versions, you can specify their variables within Ansible host_vars files.

2. Validate the playbook syntax:

   $ ansible-playbook --syntax-check ~/analysis.yml

   Note that this command only validates the syntax and does not protect against a wrong but syntactically valid configuration.

3. Run the playbook:

   $ ansible-playbook ~/analysis.yml

4. Review the output to confirm that the analysis was successful:

   RUNNING HANDLER [redhat.leapp.analysis : Pre-upgrade analysis report is done] *************************************************************************************************
   ok: [managed-node-01.example.com] => {
       "msg": "The pre-upgrade analysis report generation is now complete. SUCCESS: No inhibitors found. Review the tasks above or the result file at /var/log/leapp/leapp-report.txt."
   }

5. Review the pre-upgrade report at one of the following locations:

   • /var/log/leapp/leapp-report.txt on the managed node.
   • <workdir>/ansible_leapp_<role_name>_logs_<timestamp> directory on the control node. This directory contains subdirectories for each managed node.

Procedure

1. Review the host_vars files created by the analysis role on the control node. By default, the host_vars files are created in the playbook location. These files contain instructions on which remediate role tasks can be applied to remediate the upgrade inhibitors detected by the analysis role.

   Note

   Not all inhibitors can be remediated by the remediate Ansible role, and either must instead be remediated manually or cannot be remediated.

   The following is an example of a host_vars file:

   ---
   leapp_remediation_todo:
   - leapp_nfs_detected
   - leapp_remote_using_root
   leapp_satellite_activation_key: <activation_key>
   leapp_satellite_activation_key_post_analysis: <activation_key_post_analysis>
   leapp_satellite_activation_key_post_upgrade: <activation_key_post_upgrade>

2. Use the remediate.yml playbook, generated by the analysis role, to resolve the identified inhibitors. This playbook executes the remediation role and you can customize the playbook to meet your requirements. For example:

   ---
   - name: Remediate
     hosts: managed-node-01.example.com
     tasks:
       - name: Perform remediations on the system
         ansible.builtin.include_role:
           name: redhat.leapp.remediate

   Note

   You can also create a new remediation playbook instead of copying the generated playbook. For more information, see the /usr/share/ansible/collections/ansible_collections/redhat/leapp/roles/remediate/README.md file on the control node.

3. Validate the playbook syntax:

   $ ansible-playbook --syntax-check ~/remediate.yml

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

4. Run the playbook:

   $ ansible-playbook ~/remediate.yml

5. After remediations are applied, re-run the pre-upgrade report. For more information, see Running the pre-upgrade report by using Ansible roles.

Procedure

1. Create a playbook file, for example ~/upgrade.yml, with the following content:

   ---
   - name: RHEL upgrade
     hosts: managed-node-01.example.com
   
     tasks:
       - name: Perform OS upgrade
         ansible.builtin.import_role:
           name: redhat.leapp.upgrade
     vars:
       leapp_upgrade_type: satellite
       leapp_satellite_organization: <satellite_org>
       leapp_satellite_activation_key: <activation_key>
       leapp_satellite_activation_key_post_upgrade: <activation_key_post_upgrade>
       leapp_upgrade_opts: --target 8.10
       leapp_selinux_mode: permissive
   ...

   The settings specified in the example playbook include the following:

   leapp_upgrade_type: <upgrade_type>

   Optional: The type of upgrade being performed. The default value is cdn, which should be used for hosts registered with Red Hat CDN. Set to satellite for hosts registered with Satellite, rhui for hosts using RHUI repositories, and custom for custom repositories.

   leapp_satellite_organization: <satellite_org>

   Optional: Organization used in Satellite definition. Use only if upgrading by using Satellite. You can omit this variable if the system is registered with an activation key for the content view, including both the current RHEL version and the next version.

   leapp_satellite_activation_key: <activation_key>

   Optional: Activation key for the content view, including both the current RHEL version and the next version. Use only if upgrading by using Satellite. You can omit this variable if the system is registered with an activation key for the content view, including both the current RHEL version and the next version.

   leapp_satellite_activation_key_post_upgrade: <activation_key_post_upgrade>

   Optional: Activation key for the content view with the next RHEL version to register to after the upgrade. Use only if upgrading by using Satellite. You can omit this variable if the system is registered with an activation key for the content view, including both the current RHEL version and the next version.

   leapp_upgrade_opts: <options>

   Optional: List of command line options to run with the upgrade command, namely:

   • --target <target_os_version>
   • --enablerepo <repository_id> if you are upgrading with custom repositories
   • --no-rhsm if you are upgrading with custom repositories
   • --channel <channel> if you have an EUS or AUS subscription

   leapp_selinux_mode: <mode>

   Optional: By default, the SELinux mode on the RHEL 8 system is set to whichever mode was selected in RHEL 7. Enter enforcing, permissive, or disabled to change the mode in RHEL 8.

   For details about all variables used in the playbook, see the /usr/share/ansible/collections/ansible_collections/redhat/leapp/roles/upgrade/README.md file on the control node.

2. Validate the playbook syntax:

   $ ansible-playbook --syntax-check ~/upgrade.yml

   Note that this command only validates the syntax and does not protect against a wrong but valid configuration.

3. Run the playbook:

   $ ansible-playbook ~/upgrade.yml