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

     If your portal includes custom modules or custom themes, run a Drupal compatibility scan before you upgrade. Identifying compatibility issues early helps prevent upgrade failures. Choose one of the following options, depending on the level of validation that you need.

     • Run a basic Drupal compatibility check for the portal subsystem:

       apicops system:pre-upgrade-check portal -n namespace --drupal-scan-version <TARGET_DRUPAL_VERSION>

     • Run a comprehensive Drupal version compatibility scan and identifies potentially risky custom code patterns:

       apicops portal:compat-check -n namespace --drupal-scan-version <TARGET_DRUPAL_VERSION>

     Important: The --drupal-scan-version flag is required. The Drupal compatibility scan runs only when you include this flag.

     Use the Drupal core version that corresponds to your target API Connect version.

     Table 1. Drupal versions

     API ConnectVersion	Drupal Version
     10.0.5.3 - 10.0.8.2	10
     10.0.8.3 and later	11
     12.1.0.1 and later	11

   • Analytics subsystem:

     apicops system:pre-upgrade-check analytics -n namespace

   • For additional cluster types not covered by apicops, manually verify their status:

     oc get FederatedAPIManagementCluster -n namespace
     oc get WmAPIGatewayCluster -n namespace
     oc get DevPortalCluster -n namespace

     Confirm that all pods are READY and the status is Running.

   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.
• 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 CMS Portal.