Pre-upgrade preparation and checks on OpenShift

Create a directory called helper_files and extract the contents of helper_files.zip from the release_files.zip into the helper_files directory.

1. Get the name of the pgcluster:

   oc get pgcluster -n <management namespace>

   The response displays the name of the postgres cluster that is running in the specified namespace.

2. Check the status of the pgcluster:

   oc get pgcluster <pgcluster_name> -n <APIC_namespace> -o yaml | grep status -A 2 | tail -n3

   A successful response looks like the following example, where the state is Initialized:

   status:
       message: Cluster has been initialized
       state: pgcluster Initialized

   Important: If the pgcluster returns any other state, then do not proceed with the upgrade.

   • If backup or restore jobs are running, wait until they complete and then check the status again. Do not proceed with the upgrade until the status is Initialized.
   • If all background jobs are complete but the pgcluster does not return state: pgcluster Initialized, then contact IBM Support for assistance.

1. Verify that the apicops utility is installed and that you have the latest version by running the following command:

   apicops --version

   For more information about the apicops utility, see The API Connect operations tool: apicops.

2. Run the following command to set the KUBECONFIG environment variable.

   export KUBECONFIG=</path/to/kubeconfig>

3. Run the apicops pre-upgrade check:
   1. If using the top-level CR, the check can be run against all subsystems with a single command:

      apicops system:pre-upgrade-check apiccluster -n <namespace> [--iscp4i]

      Note: Before upgrading, run the following command to check for encryption issues and invalid gateway extensions:

      For a full check (requires admin password to verify topology)

      apicops preupgrade -n <namespace>

      To skip topology verification (no admin password needed)

      apicops preupgrade --no-topology -n <namespace>

   2. If using individual subsystem CRs:

      Run the check separately for each subsystem:
   • Management subsystem:

     apicops system:pre-upgrade-check management -n <namespace> [--iscp4i]

     Note: Before upgrading, run the following command to check for encryption issues and invalid gateway extensions:

     For a full check (requires admin password to verify topology)

     apicops preupgrade -n <namespace>

     To skip topology verification (no admin password needed)

     apicops preupgrade --no-topology -n <namespace>

   • Portal subsystem:

     apicops system:pre-upgrade-check portal -n <namespace> [--iscp4i]

   • Analytics subsystem:

     apicops system:pre-upgrade-check analytics -n <namespace> [--iscp4i]

   If your API Connect installation is part of Cloud Pak for Integration, then include the argument --iscp4i when you run the command.

   If your API Connect deployment is working correctly, the output shows no error messages.

   If the pre-upgrade check returns any errors, then collect the output and open a support case.

• Pre-upgrade preparation for air-gapped environment using a bastion host.
• Pre-upgrade preparation for air-gapped environment using a portable storage device.

• Test the upgrade in a staging environment. Use the same set of custom modules and themes, and upgrade between the same versions planned for the production deployment to validate compatibility and functionality.
• Remove problematic custom modules or themes. You can re-apply the custom themes or modules after the upgrade, if needed. For more information, see Installing custom modules.
• Take a portal backup.
• If there are any issues related custom modules or themes, contact the developer who added the modules and themes to the Developer Portal. For resolving issues outside the scope of IBM, you can contact the maintainers via the respective sites. For example, Drupal.