Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. Let us know how we can improve it.

Use the Create Issue form in Red Hat Jira to provide your feedback. The Jira issue is created in the Red Hat Satellite Jira project, where you can track its progress.

Prerequisites
Procedure

  1. Click the following link: Create Issue. If Jira displays a login error, log in and proceed after you are redirected to the form.

  2. Complete the Summary and Description fields. In the Description field, include the documentation URL, chapter or section number, and a detailed description of the issue. Do not modify any other fields in the form.

  3. Click Create.

1. Red Hat Satellite Upgrade Helper app

For interactive instructions for performing the upgrade, you can use the Red Hat Satellite Upgrade Helper on the Red Hat Customer Portal. This application provides upgrade instructions customized for your current version number of Satellite. As a result, you receive instructions that are specific to your upgrade path, as well as steps to prevent known issues. For more information, see Satellite Upgrade Helper on the Red Hat Customer Portal.

Additional resources

2. Preparing for Satellite upgrade

Review the following available upgrade paths and planning considerations before upgrading your current Red Hat Satellite installation to Red Hat Satellite 6.18.

2.1. Upgrade path overview

You can upgrade from Red Hat Satellite 6.17 to Red Hat Satellite 6.18. The upgrade process includes the following high-level steps:

  1. Ensuring that your Satellite Servers and Capsule Servers are running on Satellite 6.17.

  2. Upgrading your Satellite Server:

    1. Upgrading your Satellite Server to 6.18.

    2. Synchronizing the new 6.18 repositories.

  3. Upgrading your Capsule Servers to 6.18.

You can upgrade your Capsules separately over multiple maintenance windows because versions 6.17 and 6.16 remain compatible with your upgraded Satellite Server 6.18. Upgrading Capsules separately can be useful in the following situations:

  • If you want to have several smaller outage windows instead of one larger window.

  • If Capsules in your organization are managed by several teams and are located in different locations.

  • If you use a load-balanced configuration, you can upgrade one load-balanced Capsule and keep other load-balanced Capsules at one version lower. This allows you to upgrade all Capsules one after another without any outage.

Capsules at version 6.17 and 6.16 retain all of their previous functionality. New functionality added in the 6.18 release is available only after you upgrade your Capsules to 6.18.

2.2. Planning Satellite upgrade

Upgrading to Satellite 6.18 affects your entire Satellite infrastructure. Plan carefully before proceeding.

  • Read the Red Hat Satellite 6.18 Release notes.

  • Consider whether any of your integrations need updating. Some Satellite API endpoints, Hammer CLI commands, and modules from the Satellite Ansible Collection can differ between versions of Satellite. For information about changes in these tools, see the Red Hat Satellite 6.18 Release notes.

  • Optional: You can test the upgrade on a clone of your Satellite Server. After you successfully test the upgrade on the clone, you can repeat the upgrade on your primary Satellite Server and discard the clone. Alternately, you can promote the clone to your primary Satellite Server and discard the previous primary Satellite Server. For more information, see Cloning Satellite Server in Administering Red Hat Satellite.

  • Satellite services are shut down during the upgrade. Ensure to plan for the required downtime. The upgrade process duration varies depending on your hardware configuration, network speed, and the amount of data that is stored on the server:

    • On average installations, upgrading Satellite Server takes up to 30 minutes and upgrading a single Capsule Server takes up to 10 minutes.

    • On very large installations, upgrading Satellite Server can take up to 1 – 2 hours and upgrading a single Capsule Server can take up to 15 – 30 minutes.

2.3. Following the progress of the upgrade

Because of the lengthy upgrade time, use a utility such as tmux to suspend and reattach a communication session. You can then check the upgrade progress without staying connected to the command shell continuously.

If you lose connection to the command shell where the upgrade command is running, you can see the logs in /var/log/foreman-installer/satellite.log to check if the process completed successfully.

Additional resources

  • tmux(1) man page on your system

3. Upgrading Red Hat Satellite

Upgrading Satellite includes upgrading your Satellite Server, synchronizing the required repositories, and upgrading Capsule Servers.

3.1. Upgrading your Satellite Server

Upgrading a connected Satellite Server includes backing up the server, updating the system and Satellite configuration, and running the upgrade.

Warning
 Note that the satellite-installer is executed during an upgrade or update. Any files managed by satellite-installer are overwritten. Check if you have any manual changes that would be overwritten by satellite-installer. You can use the --noop option with the satellite-installer to test for changes. For more information, see the Red Hat Knowledgebase solution How to use the noop option to check for changes in Satellite config files during an upgrade.
Prerequisites

  • If you made manual edits to your DNS or DHCP configuration in the /etc/zones.conf or /etc/dhcp/dhcpd.conf files, ensure DNS and DHCP configuration management is disabled:

    # satellite-installer \
--foreman-proxy-dhcp-managed false \
--foreman-proxy-dns-managed false

    This prevents the upgrade process from overwriting your DNS and DHCP configuration.

  • If you use Red Hat Lightspeed advisor in Satellite in your environment, ensure you are logged in to registry.redhat.io so that the latest container images can be downloaded:

    # podman login --authfile /etc/foreman/registry-auth.json registry.redhat.io
Procedure

  1. Create a backup of your Satellite Server. The backup can be a virtual machine (VM) snapshot or a regular full backup. For more information, see Backing up Satellite Server and Capsule Server in Administering Red Hat Satellite.

  2. Ensure that the Satellite Maintenance repository is enabled:

    # subscription-manager repos --enable \
satellite-maintenance-6.18-for-rhel-9-x86_64-rpms

  3. Upgrade the satellite-maintain utility to its latest version:

    # satellite-maintain self-upgrade

  4. Determine whether your system is ready for Satellite upgrade:

    # satellite-maintain upgrade check

    Review the results and address any highlighted error conditions before performing the upgrade.

    Note

    The satellite-maintain upgrade check might prompt you for the Hammer admin user credentials. These changes are applied to the /etc/foreman-maintain/foreman-maintain-hammer.yml file.

  5. Run the Satellite Server upgrade command. Because of the lengthy upgrade time, consider using a utility such as tmux. For more information, see Following the progress of the upgrade.

    # satellite-maintain upgrade run

  6. If the satellite-maintain command told you to reboot, then reboot the system:

    # reboot

  7. Perform the following post-upgrade tasks to ensure your environment is adjusted to any changes applied during the upgrade.

    1. Verify whether the default templates changed during the upgrade. Update any custom templates that you created by cloning a default template to reflect these changes.

      Note

      Use custom provisioning snippets to execute custom code before or after the provisioning process instead of cloning default templates. You can avoid recreating cloned templates if you use custom provisioning snippets. For more information about configuring custom provisioning snippets, see Running custom code during host provisioning in Provisioning hosts.

    2. If your Satellite shows any discovered hosts, reboot them:

      1. In the Satellite web UI, navigate to Hosts > Discovered hosts.

      2. Select Any Organization to display all discovered hosts.

      3. Reboot all discovered hosts.

3.2. Synchronizing the new repositories

You must enable and synchronize the new 6.18 repositories before you can upgrade Capsule Servers and Satellite clients.

Procedure

  1. In the Satellite web UI, navigate to Content > Red Hat Repositories.

  2. Enable the following repositories:

    • Repositories required to upgrade Capsule Servers:

      • Red Hat Satellite Capsule 6.18 (for RHEL 9 x86_64) (RPMs)

      • Red Hat Satellite Maintenance 6.18 (for RHEL 9 x86_64) (RPMs)

      • Red Hat Enterprise Linux 9 (for x86_64 – BaseOS) (RPMs)

      • Red Hat Enterprise Linux 9 (for x86_64 – AppStream) (RPMs)

    • Repositories required to upgrade Satellite clients:

      • Red Hat Satellite Client 6 for each Red Hat Enterprise Linux version your clients are using

  3. In the Satellite web UI, navigate to Content > Sync Status.

  4. Synchronize the following repositories:

    • All repositories for version 6.18

    • Red Hat Satellite Client 6 repositories for each Red Hat Enterprise Linux version your clients are using

Troubleshooting

  • Refresh the Red Hat subscription manifest to resolve issues with synchronizing repositories. In the Satellite web UI, navigate to Content > Subscriptions > Manage Manifest > Refresh.

    Warning

    Do not delete the manifest from the Customer Portal or in the Satellite web UI. Deleting your manifest removes all the entitlements of your hosts.
Additional resources

  • For more information on synchronizing repositories, see Importing content in Managing content.

3.3. Upgrading Capsule Servers

After upgrading your Satellite Server and synchronizing the required repositories, you can upgrade your Capsule Servers.

Note

You can use the Capsule Upgrade Playbook job template to upgrade Capsule Servers remotely. For more information about running remote jobs based on templates, see Configuring and setting up remote jobs in Managing hosts.
Prerequisites

  • The base system of the Capsule is registered to the newly upgraded Satellite Server.

  • If the Capsule Server is registered to a content view, add the Capsule 6.18 repositories to the content view. For more information, see Synchronizing the new repositories. Publish and promote a new version of the content view. For more information, see Managing content views in Managing content.

Procedure

  1. Create a backup of your Capsule Server. The backup can be a virtual machine (VM) snapshot or a regular full backup. For more information, see Backing up Satellite Server and Capsule Server in Administering Red Hat Satellite.

  2. Upgrade the satellite-maintain utility on the Capsule Server to its latest version:

    # satellite-maintain self-upgrade

  3. Determine whether Capsule Server is ready for the upgrade:

    # satellite-maintain upgrade check

    Review the results and address any highlighted error conditions before performing the upgrade.

  4. Run the Satellite upgrade command. Because of the lengthy upgrade time, consider using a utility such as tmux. For more information, see Following the progress of the upgrade.

    # satellite-maintain upgrade run

  5. If the satellite-maintain command told you to reboot, then reboot the system:

    # reboot

3.4. Upgrading the external database operating system

If your Satellite uses an external database, you can upgrade the database from RHEL 8 to RHEL 9. You can upgrade the operating system while upgrading Satellite from 6.17 to 6.18.

Prerequisites
Procedure

  1. Create a backup of your existing external database.

  2. Restore the backup on the new Red Hat Enterprise Linux 9 server.

  3. Verify that Satellite can reach the new database:

    # PGPASSWORD='My_Foreman_Database_Password' psql -h postgres.example.com -p 5432 -U foreman -d foreman -c "SELECT 1 as ping"

  4. If your Satellite Server can reach the new database server by using the old name, no further changes are required. Otherwise, reconfigure Satellite to use the new name:

    # satellite-installer \
--foreman-db-host newpostgres.example.com \
--katello-candlepin-db-host newpostgres.example.com \
--foreman-proxy-content-pulpcore-postgresql-host newpostgres.example.com

Appendix A: Troubleshooting permission issues

Satellite upgrades perform pre-upgrade checks. If the pre-upgrade check discovers permission issues, it fails with an error similar to the following one:

2024-01-29T20:50:09 [W|app|] Could not create role 'Ansible Roles Manager': ERF73-0602 [Foreman::PermissionMissingException]: some permissions were not found:

If you see an error like this on your Satellite Server, identify and remedy the permission issues.

Procedure

  1. On your Satellite Server, identify permission issues:

    # satellite-maintain health check --label duplicate_permissions

  2. Fix permission issues:

    # foreman-rake db:seed
Verification

  • Rerun the check to ensure no permission issues remain:

    # satellite-maintain health check --label duplicate_permissions