Upgrading from v10.0.1.2 to v10.0.2.0 on VMware

You can upgrade API Connect on VMware from v10.0.1.2 or v10.0.1.2-ifix1 to v10.0.2.0

Before you begin

Before upgrading, review the supported upgrade paths: Requirements for upgrading on VMware.

About this task

You can upgrade the Management subsystem, Developer Portal subsystem, and Analytics subsystem.

For the optional components API Connect Toolkit and API Connect Local Test Environment, you do not need to upgrade. For these components, install the new version of each after you upgrade the subsystems.

Important notes:

  • When installing the new files, be sure to use the new apicup installer.
  • The upgrade order for subsystems is important. Upgrade the subsystems in the following order: (1) Management, (2) Portal, (3) Analytics, (4) Gateway. Management must be upgraded first. Gateway must be upgraded after Management because upgrading the Management service before the Gateway ensures that any new policies and capabilities will be available to a previously registered Gateway service.
  • When you run the install, the program sends the compressed tar file, which contains the upgrade images, to all cluster members. The compressed tar file is about 2 GB, and transfer can take some time. When the install command exits, the compressed tar file has arrived at each member. The upgrade process is now underway, and might continue for some time depending on factors such as the size of your deployment, your network speed, etc.
  • The apicup subsys install command automatically runs apicup health-check prior to attempting the upgrade. An error is displayed if a problem is found that will prevent successful upgrade.
Note: Upon completion of each subsystem upgrade, reboot as required:
  1. For each subsystem, the upgrade process automatically runs apicup health-check upon completion of the upgrade. When apicup health-check gives a message that reboot is required for a server, SSH onto that server and check the subsystem custom resource status:
    kubectl get <name_of_cr>

    For example:

    kubectl get managementCluster

    If both READY is True and the RECONCILED VERSION shows the version you are upgrading to, then reboot that server.

  2. During the upgrade, repeat this action for each subsystem when the message from apicup subsys health-check that says reboot is required for a server.

Procedure

  1. Complete the prerequisites:
    1. Ensure that your deployment meets the upgrade requirements. See Requirements for upgrading on VMware.
    2. Verify the API Connect deployment is healthy and fully operational. See Checking cluster health on VMware
    3. Remove any stale upgrade files: 
      apic clean-upgrade-files
    4. Complete a manual backup of the API Connect subsystems. See Backing up and restoring (v10.0.1.1 or later).
      Note: Do not start an upgrade if a backup is scheduled to run within a few hours.
    5. Do not perform maintenance tasks such as rotating key-certificates, restoring from a backup, or starting a new backup, at any time while the upgrade process is running.
  2. Optional: Take a Virtual Machine (VM) snapshot of all your VMs; see Using VM snapshots for infrastructure backup and disaster recovery for details. This action does require a brief outage while all of the VMs in the subsystem cluster are shut down - do not take snapshots of running VMs, as they might not restore successfully. VM snapshots can offer a faster recovery when compared to redeploying OVAs and restoring from normal backups.
    Important: VM snapshots are not an alternative to the standard API Connect backups that are described in the previous steps. You must complete the API Connect backups in order to use the API Connect restore feature.
  3. Download the API Connect v10.0.2.0 distribution files from IBM Fix Central. To access the files, use the link in What's new .
    Table 1. API Connect Version 10.0.2.0 product files for upgrade on VMware
    Description Files available on both Fix Central and Passport Advantage
    IBM API Connect 10.0.2.0 Management Server Upgrade File 
    upgrade_management_lts_v10.0.2.0.tgz
    IBM API Connect 10.0.2.0 Analytics Upgrade File 
    upgrade_analytics_lts_v10.0.2.0.tgz
    IBM API Connect 10.0.2.0 Portal Upgrade File 
    upgrade_portal_lts_v10.0.2.0.tgz
    IBM API Connect 10.0.2.0 VMware Install Assist for Linux, Mac, Windows

    The apicup installation utility. Required for all installations on VMware.

    		 
    apicup-linux_lts_v10.0.2.0
apicup-mac_lts_v10.0.2.0
apicup-windows_lts_v10.0.2.0.exe
    IBM API Connect 10.0.2.0 Toolkit for Linux, Mac, Windows

    Optional command line utility. See Installing the toolkit

    With Designer:

    toolkit-loopback-designer-linux_lts_v10.0.2.0.zip
toolkit-loopback-designer-mac_lts_v10.0.2.0.zip
toolkit-loopback-designer-windows_lts_v10.0.2.0.zip

    Without Designer:

    toolkit-loopback-linux_lts_v10.0.2.0.zip
toolkit-loopback-mac_lts_v10.0.2.0.zip
    IBM API Connect 10.0.2.0 Local Test Environment for Linux, OSX, Windows

    Optional test environment. See Testing an API with the Local Test Environment

    		 
    apic-lte-images-10.0.2.0.tar.gz
    IBM API Connect 10.0.2.0 Security Signature Bundle Files 
    signatures_v10.0.2.0.zip
  4. Install the installation utility.
    1. Locate the apicup installation utility file for your operating system, and place it in your project directory: 
      apicup-linux_lts_v10.0.2.0
apicup-mac_lts_v10.0.2.0
apicup-windows_lts_v10.0.2.0.exe
    2. Rename the file for your OS type to apicup. Note that the instructions in this documentation refer to apicup.
    3. OSX and Linux® only: Make the apicup file an executable file by entering chmod +x apicup.
    4. Set your path to the location of your apicup file.
      OSX and Linux 
      export PATH=$PATH:/Users/your_path/
      Windows 
      set PATH=c:\your_path;%PATH%
    5. From within your project directory, specify the API Connect license: 
      apicup license accept <License_ID>

      The <License_ID> is specific to the API Connect Program Name you purchased. To view the supported license IDs, see API Connect licenses.

  5. Upgrade the management subsystem:
    1. Install the management subsystem files.
      apicup subsys install <subsystem_name> <subsystem_upgrade_tar_archive>
    2. Verify that the upgrade was successful. 
      apicup subsys health-check <subsys_name>
    3. Reboot the subsystem when the health check command displays a message instructing you to do so. See .Reboot steps
  6. Upgrade the Portal subsystem.
    1. Install the Portal subsystem files:
      apicup subsys install <subsystem_name> <subsystem_upgrade_tar_archive>
    2. Verify that the upgrade was successful. 
      apicup subsys health-check <subsys_name>
    3. Ensure that Portal sites were installed:
      1. Use the toolkit apic to obtain the portal service id and endpoint:
        apic portal-services:get -o admin -s <management_server_endpoint> \
             --availability-zone availability-zone-default <portal-service-name> \
             --output - --format json
      2. List the sites:
        apic --mode portaladmin sites:list -s <management_server_endpoint> \
              --portal_service_id <portal_service_id_from_above_command> \
              --portal_service_endpoint <portal_service_endpoint_from_above_command> \ 
              --format json

        See also: apic sites:list and Using the sites commands.

    4. Reboot the subsystem when the health check command displays a message instructing you to do so. See Reboot steps.
  7. Upgrade the Analytics subsystem
    1. Install the Analytics subsystem files:
      apicup subsys install <subsystem_name> <subsystem_upgrade_tar_archive>
    2. Verify that the upgrade was successful. 
      apicup subsys health-check <subsys_name>
    3. Reboot the subsystem when the health check command displays a message instructing you to do so. See Reboot steps.
  8. Complete a manual backup of the API Connect subsystems. See Backing up and restoring.
  9. Optional: Take a Virtual Machine (VM) snapshot of all your VMs; see Using VM snapshots for infrastructure backup and disaster recovery for details. This action does require a brief outage while all of the VMs in the subsystem cluster are shut down - do not take snapshots of running VMs, as they might not restore successfully.
  10. Complete disaster preparation steps, to ensure recovery of API Connect from a disaster event. See Preparing for a disaster.

What to do next

When you have upgraded all of the API Connect subsystems, upgrade your DataPower Gateway Service. See Upgrading DataPower Gateway Service.