Chapter 4. Post-Upgrade Tasks

Some of the procedures in this section are optional. You can choose to perform only those procedures that are relevant to your installation.

If you use the PXE-based discovery process, then you must complete the discovery upgrade procedure on Satellite and on any Capsule Server with hosts that you want to be listed in Satellite on the Hosts > Discovered hosts page.

4.1. Upgrading Discovery

This section describes updating the PXELinux template and the boot image passed to hosts that use PXE booting to register themselves with Satellite Server.

From Satellite 6.4, provisioning templates now have a separate association with a subnet, and do not default to using the TFTP Capsule for that subnet. If you create subnets after the upgrade, you must specifically enable the Satellite or a Capsule to provide a proxy service for discovery templates and then configure all subnets with discovered hosts to use a specific template Capsule.

During the upgrade, for every subnet with a TFTP proxy enabled, the template Capsule is set to be the same as the TFTP Capsule. After the upgrade, check all subnets to verify this was set correctly.

These procedures are not required if you do not use PXE booting of hosts to enable Satellite to discover new hosts.

4.1.1. Upgrading Discovery on Satellite Server

  1. Update the Discovery template in the Satellite web UI:

    1. Navigate to Hosts > Provisioning templates.
    2. On the PXELinux global default line, click Clone.
    3. Enter a new name for the template in the Name field, for example ACME PXE global default.
    4. In the template editor field, change the line ONTIMEOUT local to ONTIMEOUT discovery and click Submit.
    5. Navigate to Administer > Settings.
    6. Locate Global default PXELinux template and click on its Value.
    7. Select the name of the newly created template from the menu and click the tick button.
    8. Navigate to Hosts > Provisioning templates.
    9. Click Build PXE Default, then click OK.
  2. In the Satellite web UI, go to Configure > Discovery Rules and associate selected organizations and locations with discovery rules.

4.1.2. Upgrading Discovery on Capsule Servers

  1. Verify that the Foreman Discovery package is current on Satellite Server. 

    # yum upgrade tfm-rubygem-foreman_discovery

  2. If an update occurred in the previous step, restart the satellite-maintain services. 

    # satellite-maintain service restart

  3. Upgrade the Discovery image on the Satellite Capsule that is either connected to the provisioning network with discovered hosts or provides TFTP services for discovered hosts. 

    # yum upgrade foreman-discovery-image

  4. On the same instance, install the package which provides the Proxy service, and then restart foreman-proxy service. 

    # yum install rubygem-smart_proxy_discovery
# service foreman-proxy restart
  5. In the Satellite web UI, go to Infrastructure > Capsules and verify that the relevant Capsule lists Discovery in the features column. Select Refresh from the Actions drop-down menu if necessary.

  6. Go to Infrastructure > Subnets and for each subnet on which you want to use discovery:

    1. Click the subnet name.
    2. On the Capsules tab, ensure the Discovery Capsule is set to a Capsule you configured above.

4.1.3. Verifying Subnets have a Template Capsule

Ensure all subnets with discovered hosts have a template Capsule:

  1. In the Satellite web UI, navigate to Infrastructure > Subnets.
  2. Select the subnet you want to check.
  3. On the Capsules tab, ensure a Template Capsule has been set for this subnet.

For more information about configuring subnets with template Capsules, see Configuring Discovery Subnets in the Red Hat Satellite Managing Hosts guide.

4.2. Updating Ansible Playbooks to Remove foreman_params

In previous versions of Satellite, Ansible playbooks used the hash foreman_params to fetch parameters, for example: 

- hosts: all
  tasks:
    - name: Print Remote Execution SSH keys
      debug:
        var: foreman_params['remote_execution_ssh_keys']

This caused problems when users wanted to import Ansible playbooks because they had to update all Ansible playbooks to use the foreman_params hash. In Satellite 6.6, the Ansible variable functionality has been enhanced and the foreman_params hash has been removed.

After you upgrade to Satellite 6.6, you must update your Ansible playbooks to remove the foreman_params hash.

Ensure that your Ansible playbooks reference variables in the following manner: 

- hosts: all
  tasks:
    - name: Print Remote Execution SSH keys
      debug:
        var: remote_execution_ssh_keys

4.3. Upgrading virt-who

If virt-who is installed on Satellite Server or a Capsule Server, it will be upgraded when they are upgraded. No further action is required. If virt-who is installed elsewhere, it must be upgraded manually.

Before You Begin

If virt-who is installed on a host registered to Satellite Server or a Capsule Server, first upgrade the host to the latest packages available in the Satellite Tools repository. For information about upgrading hosts, see Section 3.4, “Upgrading Satellite Clients”.

Upgrade virt-who Manually

  1. Upgrade virt-who. 

    # yum upgrade virt-who

  2. Restart the virt-who service so the new version is activated. 

    # systemctl restart virt-who.service

4.4. Removing the Previous Version of the Satellite Tools Repository

After completing the upgrade to Satellite 6.6, the Red Hat Satellite Tools 6.5 repository can be removed from Content Views and then disabled.

Disable Version 6.5 of the Satellite Tools Repository:

  1. In the Satellite web UI, navigate to Content > Red Hat Repositories.
  2. In the Enabled Repositories area, locate Red Hat Satellite Tools 6.5 for RHEL 7 Server RPMs x86_64.
  3. Click the Disable icon to the right.

If the repository is still contained in a Content View then you cannot disable it. Packages from a disabled repository are removed automatically by a scheduled task.

4.5. Upgrading the MongoDB Storage Engine

When you complete the upgrade, you can optionally upgrade the MongoDB storage engine to WiredTiger. Note that if you already use WiredTiger, you do not have to perform this procedure after you upgrade. If you want to use WiredTiger, you must repeat the following procedure on Satellite Server and all Capsule Servers. For more information about the WiredTiger storage engine, see WiredTiger Storage Engine in the MongoDB Manual.

Prerequisites

Before upgrading the storage engine, ensure that the following conditions exist:

  • Create a backup of the MongoDB storage.
  • Ensure that the /var/tmp directory has storage space that is at least twice the size of the /var/lib/mongodb directory.
  • Optional: On high traffic Satellite environments, use MongoDB repair to reclaim disk space. For more information, see the KCS article How to compact MongoDB files and/or reclaim disk space in "/var/lib/mongodb" in Satellite 6?.
  • Optional: On high traffic Satellite environments, use MongoDB compact to reclaim disk space. For more information, see compact in MongoDB Manual.

  • Optional: If you want to verify what version of MongoDB you currently use, enter the following command: 

    # mongo pulp_database --eval "db.serverStatus().storageEngine"

Procedure

To upgrade the MongoDB storage engine, enter the following command on Satellite Server and all Capsule Servers: 

# satellite-installer --upgrade-mongo-storage-engine

4.6. Reclaiming PostgreSQL Space After an Upgrade

When you complete the upgrade, you can perform a full database vacuum for PostgreSQL on Satellite Server to reclaim space on the migrated databases.

Procedure

On Satellite Server, to reclaim space on a PostgreSQL database, complete the following steps:

  1. To stop all services, except for the postgresql service, enter the following command: 

    # satellite-maintain service stop --exclude postgresql

  2. To switch to the postgres user and reclaim space on the database, enter the following command: 

    # su - postgres -c 'vacuumdb --full --dbname=foreman'

  3. To start the other services when the vacuum completes, enter the following command: 

    # satellite-maintain service start

4.7. Updating Templates, Parameters, Lookup Keys and Values

During the upgrade process, Satellite attempts to locate macros that are deprecated for Satellite 6.6 and converts old syntax to new syntax for the default Satellite templates, parameters, and lookup keys and values. However, Satellite does not convert old syntax in the custom templates that you have created and in the cloned templates.

The process uses simple text replacement, for example: 

@host.params['parameter1'] -> host_param('parameter1')
@host.param_true?('parameter1') -> host_param_true?('parameter1')
@host.param_false?('parameter1') -> host_param_false?('parameter1')
@host.info['parameters'] -> host_enc['parameters']
Warning

If you use cloned templates in Satellite, verify whether the cloned templates have diverged from the latest version of the original templates in Satellite. The syntax for the same template can differ between versions of Satellite. If your cloned templates contain outdated syntax, update the syntax to match the latest version of the template.

To ensure that this text replacement does not break or omit any variables in your files during the upgrade, check all templates, parameters, and lookup keys and values for the old syntax and replace manually.

The following error occurs because of old syntax remaining in files after the upgrade: 

 undefined method '#params' for Host::Managed::Jail

Fixing the outdated subscription_manager_registration snippet

Satellite 6.4 onwards uses the redhat_register snippet instead of the subscription_manager_registration snippet.

If you upgrade from Satellite 6.3 and earlier, ensure to replace the subscription_manager_registration snippet in your custom templates as follows: 

<%= snippet "subscription_manager_registration" %>
               ↓
<%= snippet 'redhat_register' %>