Pre-upgrade preparation and checks on OpenShift

Prepare your API Connect deployment on OpenShift or Cloud Pak for Integration for upgrade.

This topic covers all the preparation steps you must complete before you can start the upgrade process.

Before following the steps in this topic, review the Planning your API Connect upgrade on OpenShift to ensure that you are following a supported upgrade path and that you understand important changes that might affect your deployment.

Run the Pre-upgrade health-checks during your upgrade planning stage to identify any problems as early as possible. Run the checks again just before upgrade to confirm API Connect is still ready for upgrade.

Obtaining upgrade files

  1. Obtain the API Connect files from IBM Fix Central.
    From the IBM Fix Central site, download the following files:
    IBM® API Connect <version> for Containers
    Docker images for all API Connect subsystems. Filename is apiconnect-image-tool_<version>.
    IBM® API Connect <version> Operator Release Files for Containers
    Kubernetes operators and API Connect Custom Resource (CR) templates. Filename is apiconnect-operator-release-files_<version>.
    IBM API Connect <version> Security Signature Bundle File
    Signature files for verifying the integrity of your downloads.

    Filename is signatures_<version>.

    IBM API Connect <version> Toolkit for <operating_system>
    Toolkit command-line utility. Packaged as a stand-alone file, or with API Designer:
    • IBM API Connect <version> Toolkit for <operating_system>
    • IBM API Connect <version> Toolkit Designer for <operating_system>
    Filename is toolkit-...<operating system>_<version>.

    Not required during initial installation. After installation, you can download directly from the Cloud Manager UI and API Manager UI as explained in Installing the toolkit.

    IBM API Connect <version> Local Test Environment
    Optional test environment for testing locally as explained in Testing an API with the Local Test Environment.

    Filename is apic-lte-<operating system>_<version>.

  2. Complete the steps in Verifying the integrity of IBM product files to verify that the downloaded product files are not corrupted.
  3. Extract the IBM API Connect <version> Operator Release Files for Containers that you downloaded in step #pre_upgrade_checks_k8s__step_obtain_fc.

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

Pre-upgrade health-checks

  1. Verify that the API Connect operator and subsystems are all running.
    To verify the health of each subsystem, run the following commands:
    oc get ManagementCluster -n <management namespace>
oc get GatewayCluster -n <gateway namespace>
oc get PortalCluster -n <portal namespace>
oc get AnalyticsCluster -n <analyticsnamespace>
    Confirm that all pods are READY, for example:
    oc get PortalCluster -n apic
NAME     READY   STATUS    VERSION    RECONCILED VERSION   AGE
portal   3/3     Running   10.0.8.0   10.0.8.0-95    57m
  2. Upgrading from V10.0.5.x: Verify that the management subsystem's pgcluster is working correctly:
    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.
  3. Run the pre-upgrade health check:
    Note: If you have a 2DCDR deployment, run this check only on the active management subsystem.
    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:
      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]
      For individual CR installations, run the command for each subsystem as follows:
      • Management subsystem:
        apicops system:pre-upgrade-check management -n <namespace> [--iscp4i]
      • 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.

    Note: Cloud Pak for Integration: If you are upgrading API Connect in Cloud Pak for Integration and the pre-upgrade check indicates duplicate user accounts in the registry, resolve them now as explained in Resolving duplicate users before upgrade on Cloud Pak for Integration.

Additional pre-upgrade operations

Extra operations to review and complete before you start the upgrade.

  1. Upgrades from V10.0.5.x: If the analytics persistent queue is not enabled, verify that you have an extra Physical Volume available.

    For more information about this requirement, see Analytics persistent queue enablement requires extra PV.

  2. If analytics database backups are configured, or you want to enable them in future, then ensure that you have an extra Physical Volume available for the local backup storage. The default size is 150Gi. You can override the size during the upgrade procedure.

  3. If you used any microservice image overrides in any of your API Connect subsystem CRs, remove the image overrides before upgrade.
  4. If you are upgrading an air-gapped (disconnected from the internet) installation, configure the catalog sources for the target API Connect version on your bastion host or portable storage device:

Backup your API Connect deployment

If upgrade fails, rollback is not possible. Before upgrade complete the disaster recovery preparation for all your subsystems.

For instructions on backing up and disaster recovery preparation, see the following topics: