Upgrading Developer Portal from 2018 to v10

Upgrade the Developer Portal by installing the latest v10 with the 2018 configuration and restoring the subsystem from backups.

About this task

You will verify your configuration, create an ISO, deploy the v10 OVA file into the VM, and restore your Developer Portal data from backup.

You do not have to specify configuration settings because the Portal configuration is defined in the 2018 project directory, which you will continue to use for v10. However, you must review the backups settings.


  1. Obtain IBM® API Connect <version> Developer Portal for VMware from Fix Central, as described in Upgrading v2018 subsystems to v10.
  2. Use the version 10 release of apicup to map your 2018 configuration settings from apiconnect-up.yml to the v10 configuration file apiconnect-up-v10.yaml:
    apicup subsys get <subsystem_name>
    1. Review the output from the command, and ensure backup settings from 2018 have been set or migrated to the configuration for version 10. See Configuring backup settings for the Developer Portal subsystem.
    2. If your 2018 deployment included an extra-values-file, you must first convert the format of the file for v10. For example, if you had an extra-values-file to support multiple Portal endpoints, review the new format in the version 10 documentation. See Defining multiple portal endpoints for a VMware environment.
      Note: If your subsystem name on 2018 was greater than 63 characters, and you did not manually shorten it prior to upgrading, the upgrade shortened it automatically. To view the new subsystem name:
      apicup subsys list

      For more information, see Automatic shortening of subsystem names with greater than 63 characters

    3. Update the license value by running the following command:
      apicup licenses accept <License_ID>

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

  3. Create your ISO file in the V2018 project directory that you copied from the old deployment.
    apicup subsys install port --out portplan-out

    The --out parameter and value are required. In this example, the ISO file is created in the myProject/portplan-out directory.

  4. Deploy the file into the VM. See Deploying the Developer Portal subsystem OVA file.
  5. Verify the deployment: See Verifying deployment of the Developer Portal subsystem.
  6. Restore Portal using the backup taken on 2018. See Restoring the Developer Portal subsystem.
  7. Confirm the restore has completed successfully:
    apicup subsys health-check <portal_subsystem_name>
    When no problems are detected, the health-check commands returns silently with a 0 return code.
    Important: If the health check command states that a reboot is required, you must ensure that all Portal sites have been upgraded first before performing the reboot. To check that the Portal sites have upgraded, inspect the platform and state values for each site. The sites should all be in INSTALLED state, and have platform equal to the new platform that you can identify with platforms:list. Note that there will be two platforms present in the list while the site upgrades are happening. There should be only one platform after they have completed. To check that the Portal sites were upgraded:
    1. 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_name <portal_service_name_from_above_command> \
                    --format json

      Any sites currently upgrading will be listed as UPGRADING. Once all sites have finished upgrading they should have the INSTALLED status and the new platform version listed.

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

    3. After all sites are in INSTALLED state and have the new platform listed, run:
      apic --mode portaladmin platforms:list -s <management_server_endpoint> \
                   --portal_service_name <portal_service_name_from_above_command> \
                   --format json

      The new version of the platform should be the only platform listed.

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

    If an error is encountered, see Upgrade Limitations.

  8. Return to Upgrading v2018 subsystems to v10.