Preparing the 2018 deployment for upgrade

Prepare your 2018 deployment for upgrade to the latest v10 on VMware.

1. Ensure that the management subsystem is on a 2018 version that is supported for upgrading to the target version, as listed in Upgrade from v2018: overview and considerations.

   To view the version, ssh to the VM and run sudo -i. Use apic version. For example:

   # apic version
   INFO[0000] Log level: info  
   .
   .
   .                            
   Packages:
   .
   .
   .
   - subsystem-management:<version_number>
   

2. Make sure the API Connect cluster is healthy. For each subsystem (Management, Developer Portal, and Analytics) run the following command:

   apic health-check

   If the cluster is healthy, the health-check command returns silently with a 0 return code.

3. Remove any stale upgrade files:

   apic clean-upgrade-files

4. Complete a full backup for the API Connect v2018 Management, Portal, and Analytics subsystems. See Backing up and restoring.
   Tip: Ensure your backup archives are valid. For example:

   $ tar -tzf <FILENAME>.tar.gz >/dev/null 

   On success, the command returns to the command line prompt with no output. If there is a problem with the file, an error similar to the following would be reported:

   tar: 0511-169 A directory checksum error on media; -559038737 not equal to 67008.

5. On the v2018 management subsystem deployment, use the apicops utility to ensure the v2018 management database is consistent:

   Note that apicops is distinct from apicup.

   Important: Upgrade will fail if the apicops command is not successfully completed within 2 hours of starting the management upgrade. If the management upgrade must be run more than once, you must run the command in fix mode each time within 2 hours of starting the management upgrade.

   1. Obtain the latest v2018 release of apicops from https://github.com/ibm-apiconnect/apicops#latest-v2018-release.
   2. Download the apicops binary to one of the Management cluster servers, and make it executable:

      chmod +x apicops

      See also apicops set up requirements: https://github.com/ibm-apiconnect/apicops#requirements

   3. Run apicops as root:

      # sudo -i
      # apicops preupgrade -m fix --upgrade_to v10 -l <outputLogFileName>

      • The -m option runs the utility in fix mode. Running the utility in fix mode resolves most problems. If the utility identifies a problem it cannot resolve, contact IBM Support.
      • Set the -l option to send output to a log file.
   4. Confirm from the logs that all issues are fixed.
6. Take a backup of the Management subsystem. This backup is in addition to the backup taken in 4. The apicops preupgrade operation modifies the Management database and so it is recommended to have backups from before and after.
7. Make sure cluster is healthy before proceeding:

   apic health-check

   If the cluster is healthy, the health-check command returns silently with a 0 return code.

8. Obtain the needed upgrade script and supporting files.
   1. Go to the What's New in the latest version information page.
   2. Locate the Note: You can access the latest files from <URL link>. Select the <URL link> to go directly to the Announce page on Fix Central, where you can download files for the latest version of API Connect.
   3. Download IBM® API Connect <version> scripts and assets required for v2018 > <v10.0.1.x_version> side-by-side upgrades from API Connect Fix Central.
   4. Decompress the tar file and copy (scp) the dr-upgrade directory to the v2018 management system.

      The directory contains dr-upgrade-extract.py, which you will use to extract v2018 configuration.

9. Ensure that traffic to the management endpoints is stopped before running the python script.

   For example, a load balancer might need to mark the backends as down so that no incoming traffic is accepted.

10. Disassociate and delete your v2018 Analytics services.
    Note: Upgrading to v10 will result in the deletion of existing analytics data. For instructions on exporting data from v2018, see the v2018 documentation: https://www.ibm.com/docs/en/api-connect/2018.x?topic=analytics-exporting-api-event-data. Also, you can set up analytics offload so that all new analytics data is sent to a third-party system for storage: https://www.ibm.com/docs/en/api-connect/2018.x?topic=cloud-configuring-analytics-offload-api-connect.
    1. In Cloud Manager UI, click Topology.
    2. In the section for the Availability Zone that contains the Analytics service, locate the Gateway service that the Analytics service is associated with.
    3. Click the actions menu, and select Unassociate analytics service.
       Remember to disassociate each Analytics service from all Gateways.
    4. In the section for the Availability Zone that contains the Analytics services, locate each Analytics service and click Delete.
11. Extract the v2018 data that is needed for upgrade. Change directory to the dr-upgrade directory and run the python extract script as root:

    # sudo -i
    # python3 dr-upgrade-extract.py
    

    Tip: You can optionally run the script in the background:

    nohup python3 dr-upgrade-extract.py &> extract.log &
    tail -f extract.log
    

    • The script creates 2018-extracted-data.zip. Example output:

      .
      .
      .
      Extract job is in Running state.
      Extract job is complete
      Time elapsed: 0:06:17.397687
      Zipped 2018 extracted data and logs under '2018-extracted-data.zip'

      The amount of time required for the extraction is a function of the amount of data in the v2018 database.

      The file 2018-extracted-data.zip contains your application data in an unencrypted format. This data should be kept secure. The data is required to successfully upgrade to v10.

    • If the extract script encounters an error:
      1. Run the cleanup script:

         python3 dr-upgrade-cleanup.py

      2. Resolve the errors.
      3. Re-run the extract script:

         python3 dr-upgrade-extract.py

12. Save the following files to a location on the V10 system where you can use them for installing V10:
    • 2018-extracted-data.zip
    • The V2018 apicup project directory.
      Important: You must re-use the V2018 project directory on your new V10 system, to ensure that the encryption secret is the same and the new VM can read the data exported from the V2018 deployment.
13. Power off the virtual machine with the 2018 system.
14. Continue with Upgrading v2018 subsystems to v10.