Problem Statement

Current Red Hat Satellite upgrade documentation (for example, upgrade to Satellite 6.18) only instructs users to enable the target version maintenance repository (e.g., satellite-maintenance-6.18-for-rhel-9-x86_64-rpms). However, the documentation assumes that all prerequisite RHEL and previous Satellite repositories are already enabled, which may not always be true in customer environments.

https://docs.redhat.com/en/documentation/red_hat_satellite/6.18/html-single/upgrading_connected_red_hat_satellite_to_6.18/index 

As a result, some customers proceed with the upgrade after enabling only the new maintenance repository, while required repositories such as BaseOS, AppStream, and previous Satellite repositories remain disabled. This leads to upgrade failures, missing packages, or unexpected errors, increasing support cases and customer confusion.

The user goal is to clearly understand all required repositories that must be enabled before starting the upgrade, not just the newly introduced maintenance repository.

User Experience & Workflow

• Customer follows the official upgrade guide for Satellite (e.g., from 6.17 to 6.18).

• Documentation instructs to enable only:

• • satellite-maintenance-6.18-for-rhel-9-x86_64-rpms

• Upgrade fails or encounters package dependency issues due to missing repositories.

• Customer opens support case, causing delay and additional troubleshooting.

Requirements

• Documentation must explicitly list all repositories that must be enabled before starting the Satellite upgrade instead of assuming they are already enabled.

• The required repositories for upgrading Satellite 6.17 → 6.18 on RHEL 9 must be clearly mentioned, including:

• • rhel-9-for-x86_64-baseos-rpms

• • rhel-9-for-x86_64-appstream-rpms

• • satellite-6.17-for-rhel-9-x86_64-rpms

• • satellite-maintenance-6.17-for-rhel-9-x86_64-rpms

• • satellite-maintenance-6.18-for-rhel-9-x86_64-rpms

• Documentation should clarify that enabling only the target version maintenance repository is not sufficient for a successful upgrade.

Business Impact

If this documentation improvement is not implemented, customers will continue to face upgrade failures due to missing repositories. Improving this documentation will reduce support load, improve customer upgrade success rates, and enhance overall customer experience with Satellite lifecycle management.