Chapter 6. Assessing system-upgrade readiness with the pre-upgrade analysis task


This task is a component of the in-place upgrade capability for Red Hat Enterprise Linux using the Leapp tool. For more information about the Leapp tool and using it to check upgrade readiness manually, see Upgrading from RHEL 8 to RHEL 9, Instructions for an in-place upgrade from Red Hat Enterprise Linux 8 to Red Hat Enterprise Linux 9.

The pre-upgrade analysis task checks the readiness of systems to upgrade from Red Hat Enterprise Linux (RHEL) 8 to RHEL 9. If Insights detects upgrade-blocking issues, you can see more information about the issues, including steps to resolve them, in Insights for Red Hat Enterprise Linux on the Red Hat Hybrid Cloud Console (Console).

The pre-upgrade analysis task can run on any RHEL 8 system that is connected to Red Hat Insights using the remote host configuration (rhc) solution. You can verify that your system is connected to Insights by locating it in the Insights system inventory on the Console. If the system is not in the inventory, see Remote Host Configuration and Management documentation for information about connecting systems to Insights.

You can also run the Leapp utility manually on systems. When an Insights-connected system has a Leapp report in its archive, whether the utility was run manually or as an Insights task, you can see results from the report in Insights.

6.1. Requirements and prerequisites

The following requirements and prerequisites apply to the pre-upgrade analysis task:

  • This guide assumes that you have read and understood the in-place upgrade documentation before attempting to perform any upgrade-related action using Red Hat Insights.
  • Your systems must be eligible for in-place upgrade. See in-place upgrade documentation for system requirements and limitations.
  • Your RHEL system must be connected to Red Hat Insights using the remote host configuration solution to execute Insights tasks and other actions in a remediation plan’s playbook from the Insights for Red Hat Enterprise Linux UI.

  • You are logged in to the Red Hat Hybrid Cloud Console as a user with Tasks administrator privileges.

    Note

    All members of the Default admin access group have Tasks administrator access. If you are not a member of a User Access group with this role, you will not see any tasks on the Tasks page. For more information about User Access, including how to request greater access to Insights features, see User Access Configuration Guide for Role-based Access Control (RBAC).

6.2. Running the pre-upgrade analysis task

Use the following procedure to analyze the readiness of RHEL systems for upgrading from RHEL 8 to RHEL 9.

Prerequisites

  • Prerequisites are listed in the Requirements and prerequisites section of this chapter.

Procedure

  1. Go to the Red Hat Hybrid Cloud Console > Red Hat Insights > RHEL > Automation Toolkit > Tasks.
  2. Locate the Pre-upgrade analysis for in-place upgrade from RHEL 8 task.

    Note

    If you can not see any tasks on the page, you might not have adequate User Access. See User Access Configuration Guide for Role-based Access Control (RBAC) for more information.

  3. Optional: You can view details of the pre-upgrade analysis utility by clicking Download preview of playbook.
  4. Click Run task.
  5. On the Pre-upgrade analysis for in-place upgrade from RHEL 8 popup, select systems on which to run the pre-upgrade analysis by checking the box next to each system.

    Note

    By default, the list of systems is filtered to only display systems that are eligible to run the task. You can change or add filters to expand the parameters of included systems from your inventory.

  6. Click Execute task to run the task on the selected systems.

Verification

Use the following procedure to verify that a task has been executed successfully.

  1. Go to the Red Hat Hybrid Cloud Console > Red Hat Insights > RHEL > Automation Toolkit > Tasks page and click the Activity tab. The status of tasks, whether they are in progress or have been completed, can be viewed here.
  2. Locate your task based on the run date and time. You can see whether the task completed or failed.

    View the status of tasks

6.3. Reviewing the pre-upgrade analysis task report

After executing the pre-upgrade analysis task on systems, you can review specific details and upgrade-inhibiting recommendations for each system.

Prerequisites

  • Prerequisites are listed in the Requirements and prerequisites section of this chapter.

Procedure

  1. Go to the Red Hat Hybrid Cloud Console > Red Hat Insights > RHEL > Automation Toolkit > Tasks and click the Activity tab.
  2. Click on the task name to view the results of a task. Note the run date and time so that you select the correct report.
  3. Click on the carat next to the system name to view a list of alerts for that system.

    Upgrade-inhibiting issues shown in the task report

  4. View information about upgrade-inhibiting alerts by clicking on the carat next to an alert with a white exclamation mark inside of a red dot, accompanying red alert text.

    Note

    In addition to the inhibitor alerts, you might also see lower severity and informative alerts that do not require remediation in order for the upgrade to proceed.

  5. Review the report thoroughly. While some recommendations may be informational, it is crucial to take action if you encounter any errors or warnings. In the event of such issues, address them on your systems and re-run the pre-upgrade task to assess the impact of your remediation efforts.

    Note

    Certain errors are classified as official inhibitors, and proceeding with the upgrade is not possible until these are remediated.

6.4. Viewing upgrade-inhibiting recommendations

After running the pre-upgrade analysis task, or manually running the Leapp tool on individual systems, you can view a list of recommendations for upgrade-inhibiting issues in your infrastructure.

Using the list of pre-upgrade recommendations, you can view the following information about each recommendation:

  • Recommendation details
  • Affected-system information
  • Total risk and impact insights
  • Risk to system availability during resolution actions

Prerequisites

  • Any user with default access (the default for every user) can view the list of in-place upgrade recommendations.

Procedure

  1. Go to Red Hat Insights > Operations > Advisor > Topics > In-place upgrade to view recommendations affecting the success of in-place upgrades.

    Note

    Currently, the in-place upgrade recommendations list only shows recommendations that Insights has identified as upgrade inhibitors. You can see all in-place upgrade recommendations, including non-inhibitors, in the detailed view of each executed task.

6.5. Remediating upgrade-inhibiting recommendations

You can use the in-place upgrade recommendations list as a basis for remediating upgrade-inhibiting issues on systems in your infrastructure.

Some recommendations have a playbook available for automating the execution of remediations directly from the Insights for Red Hat Enterprise Linux UI. However, some recommendations require manual resolutions, the steps of which are customized for the system and recommendation pair, and are provided with the recommendation. You can tell which recommendations have playbooks available by viewing the Remediation type column in the recommendations table.

  • To find the recommendations that have playbooks available to execute, use the filter and sort options at the top of the table to narrow down the list.

    • To filter the recommendations, use the search bar or select a specific item from the dropdown menu.
    • To sort the recommendations , click the Remediation type column header.

For more information about Insights remediations, see the Red Hat Insights Remediations Guide.

6.5.1. Remediating RHEL upgrade-inhibiting recommendations by creating a remediation plan in Insights

You can automate the remediation of upgrade-inhibiting recommendations by creating a remediation plan in Insights. When you create a remediation plan, Insights generates an Ansible Playbook to execute the actions needed to remediate the issue on a selected system or group of systems.

Use the following procedure to locate your inhibitor issues and select recommendations and systems to remediate.

Prerequisites

  • Prerequisites are listed in the Requirements and prerequisites section of this chapter.

Procedure

  1. Go to Red Hat Insights > Operations > Advisor > Topics > In-place upgrade. A table that lists all of the recommended remediations affecting the success of in-place upgrades displays.
  2. Use the filter and sort options at the top of the table to narrow down the list of recommendations.

    1. To filter the recommendations, use the search bar or select a specific item from the dropdown menu.
    2. To sort the recommendations, click the column headers such as Name, Remediation type, Systems, or Total risk.
  3. Choose a recommendation with a Remediation type of Playbook.

    Note: You can tell which recommendations have playbooks available by viewing and sorting the Remediation type column.

    Recommendations table view for in-place upgrades

  4. For each recommendation with an available playbook, take the following actions:

    1. Click the recommendation to see more information about the issue, including the systems that are affected.
    2. Check the box next to each system you want to add to the playbook and click Plan remediation.

      Select systems then click Remediate.

    3. In the pop-up, select Create a new playbook and enter a name for the playbook, then click Next.
    4. Optional: Alternatively, you can add the resolution for the selected systems to an existing playbook.
    5. Review the included systems and click Next.
    6. Review the included recommendation. You can click the carat next to the recommendation name to see included systems.

      Important

      Some resolutions require the system to reboot. Auto reboot is not enabled by default but you can enable it by clicking Turn on autoreboot above the list of recommendations.

    7. Click Submit. The final pop-up view confirms that the playbook was created successfully. You can select to return to the application or open the playbook.
  5. Find the playbook in Automation Toolkit > Remediations and click it to open it.
  6. The playbook includes a list of actions. Select the actions to execute by checking the box next to each one.
  7. Click Execute playbook to run the playbook on the specified systems.
  8. On the pop-up, click the Execute playbook on systems button. The playbook runs on those systems.

6.5.2. Remediating RHEL upgrade-inhibiting recommendations manually

You can remediate upgrade-inhibiting recommendations by manually applying resolution steps on affected systems. The following procedure shows how to find the resolution steps for a system and recommendation pairing.

Prerequisites

  • Prerequisites are listed in the Requirements and prerequisites section of this chapter.

Procedure

  1. Go to Red Hat Insights > Operations > Advisor > Topics > In-place upgrade to view recommendations affecting the success of in-place upgrades.
  2. Choose a recommendation with the word "Manual" in the *Remediation tab, which indicates that the issue requires manual remediation.

    Recommendations for in-place upgrades

  3. For each recommendation requiring a manual remediation, take the following actions:

    1. Click on the recommendation to open the recommendation-details page, which shows affected systems.

      An upgrade inhibiting recommendation with affected systems

    2. Click on a system name.
    3. Pick a recommendation to resolve manually and click on the carat to view the Steps to resolve the recommendation on the system.
    4. Perform the resolution steps on the system.
    5. Repeat steps b, c, and d for each affected system.
Back to top
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

© 2025 Red Hat, Inc.