This documentation is for WSO2 API Manager 2.5.0 View documentation for the latest release.
Upgrading from the Previous Release in a Distributed Deployment - API Manager 2.5.0 - WSO2 Documentation

All docs This doc
||
Skip to end of metadata
Go to start of metadata

Note that this page is WIP.  Work on 2.0.0 to 2.5.0  upgrade has been completed.


The following information describes how to upgrade your API Manager server from APIM 1.8.0/1.9.0/1.9.1/1.10.0/2.0.0/2.1.0/2.2.0 to 2.5.0

To upgrade from a version older than 1.8.0, follow the instructions in the document that was released immediately after your current release and upgrade incrementally.

Before you begin

  • This release is a WUM-only release. This means that there are no manual patches. Any further fixes or latest updates for this release can be updated through the WSO2 Update Manager (WUM).
    • If you are upgrading to this version to use this version in your production environment, use the WSO2 Update Manager and get the latest available updates for WSO2 API Manager 2.5.0. For more information on how to do this, see Updating WSO2 Products.
  • Make sure you have set up your distributed environment with APIM 2.5.0.

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.2.0 to 2.5.0

If you are using WSO2 IS as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the API Manager configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

In this section, you move all existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the synapse configs of all the tenants and super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 
    If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.5.0 from https://wso2.com/api-management/.
  3. Open the <API-M_2.5.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current API Manager instance already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (If statistics are configured)
  4. Edit the registry configurations in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/user-mgt.xml file, similar to the configurations of the current API Manager.

    In a clustered/distributed API Manager setup, follow step 5 on the Gateway node.

  5. Move all your synapse configurations to API-M 2.5.0 pack by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory to the <API-M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default directory. Similarly, move all your tenant synapse configurations by copying and replacing the  <CURRENT_API-M_HOME>/repository/tenants directory to the  <API-M_2.5.0_MANAGER_HOME>/repository/tenants directory.
  6. If you manually added any custom OSGI bundles to the <API-M_2.2.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.5.0_HOME>/repository/components/dropins directory.

  7. If you manually added any JAR files to the <API-M_2.2.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.5.0_HOME>/repository/components/lib directory.

Step 2 - Upgrade API Manager to 2.5.0

  1. Stop all running WSO2 API Manager server instances.
  2. Make sure you backed up all the databases and synapse configs, as instructed in step 1 of the previous section.

  3. To start the migration process, run the respective migration script based on your environment. 

    Run the apim220_to_apim250_gateway_artifact_migrator.sh script, as shown below, to migrate from API Manager 2.2.0 to 2.5.0. 

    ./apim220_to_apim250_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.2.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.5.0_HOME>/repository/tenants

    Where, <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    Run the PowerShell script apim220_to_apim250_gateway_artifact_migrator.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim220_to_apim250_gateway_artifact_migrator.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.2.0 deployment, reside.

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    Run the PowerShell script apim220_to_apim250_gateway_artifact_migrator_for_tenants.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim220_to_apim250_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.2.0 deployment, reside.

    • Tenants - <API-M_2.5.0_HOME>/repository/tenants

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    It may take a considerable amount of time, proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim220_to_apim250_gateway_artifact_migrator.ps1 / apim220_to_apim250_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim220_to_apim250_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal/command-line as the Administrator.

    Set-ExecutionPolicy RemoteSigned
  4. Upgrade the API Manager database from version 2.2.0 to version 2.5.0.

    1. Download apimgt-db-migration-scripts-2.2to2.5.zip and extract it.

    2. Execute the relevant database script on the WSO2AM_DB from the scripts provided in the extracted directory.

  5. Upgrade the Identity component in WSO2 API Manager from version 5.5.0 to 5.6.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the wso2is-5.x.x-migration.zip and extract it.
    2. Copy the migration-resources folder from the extracted folder to the <API-M_2.5.0_HOME> directory.
    3. Open the migration-config.yaml file in the migration-resources directory and make sure the currentVersion element to 5.5.0, as shown below.

      migrationEnable: "true"
      
      currentVersion: "5.5.0"
      migrateVersion: "5.6.0"

      Make sure you have enabled migration by setting the migrationEnable element to true.

    4. From the extracted folder, copy the org.wso2.carbon.is.migration-5.6.0.jar to the <API-M_2.5.0_HOME> / repository/components/dropins directory.

    5. Copy and replace the keystores used in the previous version to the <API-M_2.5.0_HOME>/repository/resources/security directory.

      Start API Manager 2.5.0 with the command line option -Dmigrate -Dcomponent=identity as follows to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

    6. After you have successfully completed the migration, stop the server and remove the following files and folders.

      1. Remove the org.wso2.carbon.is.migration-5.6.0.jar file, which is in the <API-M_2.5.0_HOME>/repository/components/dropins directory.

      2. Remove the migration-resources directory, which is in the <API-M_2.5.0_HOME> directory.

      3. If you ran WSO2 API-M as a Windows Service when doing the identity component migration, then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity

  6. Re-index the artifacts in the registry.

    1. Run the reg-index.sql script against the REG_DB database.

    2. Add the tenantloader-1.0.jar to <API-M_2.5.0_HOME>/repository/components/dropins directory

    3. Rename the <lastAccessTimeLocation> element in the <API-M_2.5.0_HOME>/repository/conf/registry.xml file.

    4. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    5. If the <API-M_2.5.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    6. Start the WSO2 API-M server.
    7. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.5.0_HOME>/repository/components/dropins directory.

Step 3 - Migrate the configurations for API-M Analytics

This step is required only if you have API-M-Analytics configured in your current deployment.

Follow the steps below to migrate the configurations required to run API-M Analytics for WSO2 API-M 2.5.0 if you are upgrading from APIM Analytics 2.2.0.

  1. Download WSO2 API Manager Analytics 2.5.0 from here.
  2. If you want to connect your WSO2 API Manager Analytics 2.5.0 installation to the same databases that were used with your API Manager Analytics 2.2.0 installation, edit the configurations in the <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/analytics/rdbms-config.xml file, similar to the configurations in the same file of your WSO2 API Manager Analytics 2.2.0 installation.
  3. Replace the Statistics DB (STAT_DB) configurations in the <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/stats-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.2.0 Installation.
  4. Remember to copy and replace the keystores used in the previous version to the <API-M_ANALYTICS_2.5.0_HOME> / repository/resources/security directory.

Step 4 - Start the WSO2 API-M server

sh wso2server.sh

wso2server.bat

This concludes the upgrade process.

Tip 1: The migration client that you use in this guide automatically migrates your tenants, workflows, external user stores, etc. to the upgraded environment. There is no need to migrate them manually.

Tip 2: If you are using an SVN based deployment synchronizer, start with a clean SVN repository and point the new deployment nodes to the new SVN repository. Also, any existing .svn directories in the new deployment's <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.5.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.1.0 to 2.5.0

If you are using WSO2 IS as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the API Manager configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

In this section, you move all existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the synapse configs of all the tenants and super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 
    If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.5.0 from https://wso2.com/api-management/.
  3. Open the <API-M_2.5.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current API Manager instance already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (If statistics are configured)
  4. Edit the registry configurations in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/user-mgt.xml file, similar to the configurations of the current API Manager. 

    In a clustered/distributed API Manager setup, follow steps 5 and 6 for the Gateway node.

  5. Move all your synapse configurations, except the files mentioned below, by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory to the <API-M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default directory. 

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to API Manager 2.5.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, please merge them to the corresponding files in 2.5.0.

    /api/_AuthorizeAPI_.xml
    /api/_RevokeAPI_.xml
    /api/_TokenAPI_.xml
    /api/_UserInfoAPI_.xml
    /sequences/_auth_failure_handler_.xml
    /sequences/_build_.xml
    /sequences/_cors_request_handler_.xml
    /sequences/fault.xml
    /sequences/main.xml
    /sequences/_production_key_error_.xml
    /sequences/_resource_mismatch_handler_.xml
    /sequences/_sandbox_key_error_.xml
    /sequences/_throttle_out_handler_.xml
    /sequences/_token_fault_.xml
    /proxy-services/WorkflowCallbackService.xml
  6. Move all your tenant synapse configurations by updating the configurations made in the <CURRENT_API-M_HOME>/repository/tenants directory to the <API-M_2.5.0_MANAGER_HOME>/repository/tenants directory.

    NOTE: Get the files listed below from the <API-M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and replace the corresponding files in the <API-M_2.5.0_MANAGER_HOME>/repository/tenants/<tenant-id>/synapse-configs/default/sequences directory.

    _auth_failure_handler_.xml
    _cors_request_handler_.xml
    fault.xml
    main.xml
    _production_key_error_.xml
    _resource_mismatch_handler_.xml
    _sandbox_key_error_.xml
    _throttle_out_handler_.xml

    In a clustered/distributed API Manager setup, do this step on the Gateway node.

  7. If you manually added any custom OSGI bundles to the <API-M_2.1.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.5.0_HOME>/repository/components/dropins directory.

  8. If you manually added any JAR files to the <API-M_2.1.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.5.0_HOME>/repository/components/lib directory.

Step 2 - Upgrade API Manager to 2.5.0

  1. Stop all running WSO2 API Manager server instances.
  2. Make sure you backed up all the databases and synapse configs, as instructed in step 1 of the previous section.

  3. To start the migration process, run the respective migration script based on your environment. 

    Run the apim210_to_apim250_gateway_artifact_migrator.sh script, as shown below, to migrate from API Manager 2.1.0 to 2.5.0. 

    ./apim210_to_apim250_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.1.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.5.0_HOME>/repository/tenants

    Where, <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    Run the PowerShell script apim210_to_apim250_gateway_artifact_migrator.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim210_to_apim250_gateway_artifact_migrator.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.1.0 deployment, reside.

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    Run the PowerShell script apim210_to_apim250_gateway_artifact_migrator_for_tenants.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim210_to_apim250_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.1.0 deployment, reside.

    • Tenants - <API-M_2.5.0_HOME>/repository/tenants

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    It may take a considerable amount of time, proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim210_to_apim250_gateway_artifact_migrator.ps1 / apim210_to_apim250_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim210_to_apim250_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal/command-line as the Administrator.

    Set-ExecutionPolicy RemoteSigned
  4. Upgrade the API Manager database from version 2.1.0 to version 2.5.0.

    1. Download apimgt-db-migration-scripts-2.1to2.5.zip and extract it.

    2. Execute the relevant database script on the WSO2AM_DB from the scripts provided in the extracted directory.

  5. If your MB Store database in version 2.1.0 is not the default h2 DB, upgrade the MB Store database from version 3.1.0 to version 3.2.0.

    It is recommended to use the default h2 database for MB store database in API-Manager.

    1. Download mb-store-migration-scripts-3.1.0_to_3.2.0.zip and extract it.

    2. Execute the relevant database script on the WSO2_MB_STORE_DB from the scripts provided in the extracted directory.

  6. Upgrade the Identity component in WSO2 API Manager from version 5.3.0 to 5.6.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the wso2is-5.x.x-migration.zip and extract it.
    2. Copy the migration-resources folder from the extracted folder to the <API-M_2.5.0_HOME> directory.
    3. Open the migration-config.yaml file in the migration-resources directory and edit the currentVersion element to 5.3.0, as shown below.

      migrationEnable: "true"
      
      currentVersion: "5.3.0"
      migrateVersion: "5.6.0"

      Make sure you have enabled migration by setting the migrationEnable element to true.

    4. Remove the following entry from the migration-config.yaml file.

         -
          name: "EventPublisherMigrator"
          order: 11
    5. From the extracted folder, copy the org.wso2.carbon.is.migration-5.6.0.jar to the <API-M_2.5.0_HOME> / repository/components/dropins directory.

    6. Copy and replace the keystores used in the previous version to the <API-M_2.5.0_HOME>/repository/resources/security directory.

    7. Start API Manager 2.5.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity

      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

    8. After you have successfully completed the migration, stop the server and remove the following files and folders.

      1. Remove the org.wso2.carbon.is.migration-5.6.0.jar file, which is in the <API-M_2.5.0_HOME>/repository/components/dropins directory.

      2. Remove the migration-resources directory, which is in the <API-M_2.5.0_HOME> directory.

        • Page not found for multiexcerpt macro.
        The page: Upgrading from the Previous Release for a Single Node Deployment was not found. Please check/update the page name used in the 'multiexcerpt-include macro.

  7. If you are upgrading from a vanilla distribution of API Manager 2.1.0 or a WUM updated distribution taken before 5th December 2017 of API Manager 2.1.0, you have to run the following migration client for migrating Access Control support for API Publisher because Publisher Access Control is enabled by default in API Manager 2.5.0. If not, you can skip this step.

    1. Download the Access Control Migration Client from here and copy it to the <API-M_HOME>/repository/components/dropins directory.

    2. Start the server with -DmigrateAccessControl=true as follows.

      sh wso2server.sh -DmigrateAccessControl=true
  8. Re-index the artifacts in the registry.

    1. Shut down WSO2 API Manager 2.5.0 (if you have already started it).

    2. Run the reg-index.sql script against the REG_DB database.

    3. Add the tenantloader-1.0.jar to <API-M_2.5.0_HOME>/repository/components/dropins directory

    4. Rename the <lastAccessTimeLocation> element in the <API-M_2.5.0_HOME>/repository/conf/registry.xml file.

    5. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    6. If the <API-M_2.5.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    7. Start the WSO2 API-M server.
    8. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.5.0_HOME>/repository/components/dropins directory.
      If you followed the previous step, make sure to remove the WSO2 API-M client migration ZIP ( wso2-api-migration-client.zip ) from the <API-M_2.5.0_HOME>/repository/components/dropins directory as well.

Step 3 - Migrate the configurations for API-M Analytics

This step is required only if you have API-M-Analytics configured in your current deployment.

Follow the steps below to migrate the configurations required to run API-M Analytics for WSO2 API-M 2.5.0 when you are upgrading from APIM Analytics 2.1.0.

  1. Download WSO2 API Manager Analytics 2.5.0 from here.
  2. If you want to connect your WSO2 API Manager Analytics 2.5.0 installation to the same databases that were used with your API Manager Analytics 2.1.0 installation, edit the configurations in the <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/analytics/rdbms-config.xml file, similar to the configurations in the same file of your WSO2 API Manager Analytics 2.1.0 installation.
  3. Replace the Statistics DB (STAT_DB) configurations in the <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/stats-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.1.0 Installation.
  4. Remember to copy and replace the keystores used in the previous version to the <API-M_ANALYTICS_2.5.0_HOME>/repository/resources/security directory.

Step 4 - Start the WSO2 API-M server

sh wso2server.sh

wso2server.bat


This concludes the upgrade process.

Tip 1: The migration client that you use in this guide automatically migrates your tenants, workflows, external user stores, etc. to the upgraded environment. There is no need to migrate them manually.

Tip 2: If you are using an SVN based deployment synchronizer, start with a clean SVN repository and point the new deployment nodes to the new SVN repository. Also, any existing .svn directories in the new deployment's <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.5.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.0.0 to 2.5.0

If you are using WSO2 IS as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the API Manager configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

In this section, you move all existing API Manager configurations from the current environment to the new one. Follow the instructions below for the respective instances.

On the Database (s)
  1. Back up all of the databases.
  2. Drop the current mb store database (mbstoredb) and create a new database using the relevant DB script found at API-M 2.5.0 <API-M_HOME/dbscripts/mb-store/.
On Gateway instance(s) only
  1. Make sure you have a back up of all databases used by your API Manager instances.
  2. Back up  the synapse configs of all the tenants and super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 
    If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.
  3. Download API Manager 2.5.0 from https://wso2.com/api-management/.
  4. Open the <API-M_2.5.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current API Manager instance already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (if statistics are configured)
  5. Edit the registry configurations in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/user-mgt.xml file similar to the configurations of the current API Manager.
  6. Move all your synapse configurations, except the files mentioned below, by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory in the <API-M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default directory.

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to API Manager 2.5.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, please merge them to the corresponding files in 2.5.0.

    /api/_AuthorizeAPI_.xml
    /api/_RevokeAPI_.xml
    /api/_TokenAPI_.xml
    /api/_UserInfoAPI_.xml
    /sequences/_auth_failure_handler_.xml
    /sequences/_build_.xml
    /sequences/_cors_request_handler_.xml
    /sequences/fault.xml
    /sequences/main.xml
    /sequences/_production_key_error_.xml
    /sequences/_resource_mismatch_handler_.xml
    /sequences/_sandbox_key_error_.xml
    /sequences/_throttle_out_handler_.xml
    /sequences/_token_fault_.xml
    /proxy-services/WorkflowCallbackService.xml
  7. Move all your tenant synapse configurations by updating the configurations made in the <CURRENT_API-M_HOME>/repository/tenants directory to the <API-M_2.5.0_MANAGER_HOME>/repository/tenants directory.

    NOTE: Get the files listed below from the <API-M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and replace the corresponding files in the <API-M_2.5.0_MANAGER_HOME>/repository/tenants/<tenant-id>/synapse-configs/default/sequences directory.

    _auth_failure_handler_.xml
    _cors_request_handler_.xml
    fault.xml
    main.xml
    _production_key_error_.xml
    _resource_mismatch_handler_.xml
    _sandbox_key_error_.xml
    _throttle_out_handler_.xml
  8. If you manually added any custom OSGI bundles to your previous Gateway node in the <API-M_2.2.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.5.0_HOME>/repository/components/dropins directory.

  9. If you manually added any JAR files to your previous Gateway node in the <API-M_2.2.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.5.0_HOME>/repository/components/lib directory.

On Publisher, Store and Key Manager instance(s)
  1. Make sure you have a back up of all databases used by your API Manager instances.

  2. Download API Manager 2.5.0 from https://wso2.com/api-management/.
  3. Open the <API-M_2.5.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current API Manager instance already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (if statistics are configured)
  4. Edit the registry configurations in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/user-mgt.xml file similar to the configurations of the current API Manager.
  5.  In the same file as step 5, (<API-M_2.5.0_MANAGER_HOME>/repository/conf/user-mgt.xml) modify the <AuthorizationManager> to add the following property.

    <AuthorizationManager 
    class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">
        ...
        <Property name="PreserveCaseForResources">false</Property>
    </AuthorizationManager>
  6. If you manually added any custom OSGI bundles to your previous Publisher, Store, or Key Manager instances in the <API-M_2.2.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.5.0_HOME>/repository/components/dropins directory.

  7. If you manually added any JAR files to your previous Publisher, Store, or Key Manager instances in the <API-M_2.2.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.5.0_HOME>/repository/components/lib directory.


Step 2 - Upgrade API Manager to 2.5.0

  1. Stop all running WSO2 API Manager server instances.
  2. Make sure you backed up all the databases and synapse configs as instructed in step 1 of the previous section.

  3. Upgrade the API Manager database from version 2.0.0 to version 2.5.0.

    1. Download the apimgt-db-migration-scripts-2.0to2.5.zip and extract it.

    2. Execute the relevant database script on WSO2AM_DB from the scripts provided in the extracted directory

  4. Copy and replace the keystores used in the previous version to the <API-M_2.5.0_HOME>/repository/resources/security directory in all nodes.

  5. Follow the instructions below on each respective node.

on Gateway Instance(s)
  1. To start the migration process, run the respective migration script based on your environment.

    Run the apim200_to_apim250_gateway_artifact_migrator.sh  script, as shown below, to migrate from API Manager 2.0.0 to 2.5.0. 

    ./apim200_to_apim250_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.0.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.5.0_HOME>/repository/tenants

    Where, <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0. 

    Run the PowerShell script apim200_to_apim250_gateway_artifact_migrator.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim200_to_apim250_gateway_artifact_migrator.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.0.0 deployment, reside.

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    Run the PowerShell script apim200_to_apim250_gateway_artifact_migrator_for_tenants.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim200_to_apim250_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.0.0 deployment, reside.

    • Tenants - <API-M_2.5.0_HOME>/repository/tenants

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    It may take a considerable amount of time, proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim200_to_apim250_gateway_artifact_migrator.ps1 / apim200_to_apim250_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim200_to_apim250_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal/command-line as the Administrator.

    Set-ExecutionPolicy RemoteSigned
on Key Manager Instance(s)
  1. Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.6.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the wso2is-5.x.x-migration.zip and extract it.
    2. Copy the migration-resources folder in the extracted folder to the <API-M_2.5.0_HOME>.

    3. Open the migration-config.yaml file in the migration-resources directory and edit the currentVersion element to 5.2.0, as shown below.

      migrationEnable: "true"
      
      currentVersion: "5.2.0"
      migrateVersion: "5.6.0"

      Make sure you have enabled migration by setting the migrationEnable element to true.

    4. Remove the following entries from the migration-config.yaml file.

         -
          name: "EventPublisherMigrator"
          order: 11

      and

         -
          name: "ChallengeQuestionDataMigrator"
          order: 5
          parameters:
            schema: "identity"
    5. From the extracted folder, copy the org.wso2.carbon.is.migration-5.6.0.jar to the <API-M_2.2.0_HOME>/repository/components/dropins directory.

    6. Start API Manager 2.5.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity comonent migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity -Dprofile=api-key-manager
      wso2server.bat -Dmigrate -Dcomponent=identity -Dprofile=api-key-manager

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

    7. After you have successfully completed the migration, stop the server and remove the following files and folders.

      1. Remove the org.wso2.carbon.is.migration-5.6.0.jar file, which is in the <API-M_2.5.0_HOME>/repository/components/dropins directory.

      2. Remove the migration-resources directory, which is in the <API-M_2.5.0_HOME> directory.

      3. If you ran WSO2 API-M as a Windows Service when doing the identity component migration, then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity
on Publisher instance(s)
  1. You have to run the following migration client for migrating Access Control support for API Publisher because Publisher Access Control is enabled by default in API Manager 2.5.0.


    1. Download  the Access Control Migration Client from here  and copy it to the  <API-M_HOME>/repository/components/dropins  directory.

    2. Start the server with -DmigrateAccessControl=true as follows.

      sh wso2server.sh -DmigrateAccessControl=true -Dprofile=api-publisher
  2. Re-index the artifacts in the registry.

    1. Shut down WSO2 API Manager 2.5.0 (if you have already started it).

    2. Run the reg-index.sql script against the REG_DB database.

    3. Add the tenantloader-1.0.jar to <API-M_2.5.0_HOME>/repository/components/dropins directory

    4. Rename the <lastAccessTimeLocation> element in the <API-M_2.5.0_HOME>/repository/conf/registry.xml file.

    5. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    6. If the <API-M_2.5.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    7. Start the WSO2 API-M server.

    8. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.5.0_HOME>/repository/components/dropins directory.

Step 3 - Migrate the configurations for API-M Analytics

This step is required only if you have API-M-Analytics configured in your current deployment.

Follow the steps below to migrate the configurations required to run API-M Analytics for WSO2 API-M 2.5.0 when you are upgrading from APIM Analytics 2.0.0.

  1. Download WSO2 API Manager Analytics 2.5.0 from here.
  2. Replace the Analytics database configurations in the <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/datasources/analytics-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.0.0 Installation
  3. Replace the Statistics DB (STAT_DB) configurations in the <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/datasources/stats-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.0.0 Installation.
  4. Remember to copy and replace the keystores used in the previous version to the <API-M_ANALYTICS_2.5.0_HOME>/repository/resources/security directory.

Start 4 - Start the WSO2 API-M server

Start the WSO2 API Manager profiles in the following order.

For more information on optimizing the API-M profile before or after starting the WSO2 API-M profiles, see Starting an API-M profile.

  1. Start the Key Manager.

    cd <API-M_HOME>/bin/
    sh wso2server.sh -Dprofile=api-key-manager
    cd <API-M_HOME>\bin\
    wso2server.bat --run -Dprofile=api-key-manager
  2. Start the API Publisher.

    cd <API-M_HOME>/bin/
    sh wso2server.sh -Dprofile=api-publisher
    cd <API-M_HOME>\bin\
    wso2server.bat --run -Dprofile=api-publisher
  3. Start the API Store.

    cd <API-M_HOME>/bin/
    sh wso2server.sh -Dprofile=api-store
    cd <API-M_HOME>\bin\
    wso2server.bat --run -Dprofile=api-store
  4. Start the API Traffic Manager.

    cd <API-M_HOME>/bin/
    sh wso2server.sh -Dprofile=traffic-manager
    cd <API-M_HOME>\bin\
    wso2server.bat --run -Dprofile=traffic-manager
  5. Start the Gateway Manager.

    cd <API-M_HOME>/bin/
    sh wso2server.sh -Dprofile=gateway-worker
    cd <API-M_HOME>\bin\
    wso2server.bat --run -Dprofile=gateway-worker

This concludes the upgrade process.

Tip 1: The migration client that you use in this guide automatically migrates your tenants, workflows, external user stores, etc. to the upgraded environment. There is no need to migrate them manually.

Tip 2: If you are using an SVN based deployment synchronizer, start with a clean SVN repository and point the new deployment nodes to the new SVN repository. Also, any existing .svn directories in the new deployment's <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.5.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

Follow the instructions below to upgrade your WSO2 API Manager server from APIM 1.10.0 to 2.5.0

If you are using WSO2 IS as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

In this section, you move all existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the synapse configs of all the tenants and super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 
    If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.5.0 from http://wso2.com/api-management/.
  3. Open the <API-M_2.5.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current API Manager instance already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (if statistics are configured)
  4. Edit the registry configurations in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.5.0_MANAGER_HOME>/repository/conf/user-mgt.xml file similar to the configurations of the current API Manager. 

    In a clustered/distributed API Manager setup, follow steps 5 and 6 for the Gateway node.

  5. Move all your synapse configurations, except the files mentioned below, by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory to the <API-M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default. 

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to APIM 2.5.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, please merge them to the corresponding files in 2.5.0.

    /api/_AuthorizeAPI_.xml
    /api/_RevokeAPI_.xml
    /api/_TokenAPI_.xml
    /api/_UserInfoAPI_.xml
    /sequences/_auth_failure_handler_.xml
    /sequences/_build_.xml
    /sequences/_cors_request_handler_.xml
    /sequences/fault.xml
    /sequences/main.xml
    /sequences/_production_key_error_.xml
    /sequences/_resource_mismatch_handler_.xml
    /sequences/_sandbox_key_error_.xml
    /sequences/_throttle_out_handler_.xml
    /sequences/_token_fault_.xml
    /proxy-services/WorkflowCallbackService.xml
  6. Move all your tenant synapse configurations by updating the configurations made in the <CURRENT_API-M_HOME>/repository/tenants directory to the <API-M_2.5.0_MANAGER_HOME>/repository/tenants directory.

    NOTE: Get the files listed below from the <API_M_2.5.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and replace the corresponding files in the  <API_M_2.5.0_MANAGER_HOME>/repository/tenants/<tenant-id>/synapse-configs/default/sequences directory.

    _auth_failure_handler_.xml
    _cors_request_handler_.xml
    fault.xml
    main.xml
    _production_key_error_.xml
    _resource_mismatch_handler_.xml
    _sandbox_key_error_.xml
    _throttle_out_handler_.xml

    In a clustered/distributed API Manager setup, do this step for the Gateway node.

  7. If you have documentation defined for your APIs, make sure you add a value to the Documentation Summary  field. 
    Documentation summary is mandatory in APIM 2.0.0 onwards. Trying to migrate with an empty documentation summary field from an older version can cause issues in the migration. 

  8. If you manually added any custom OSGI bundles to the <API-M_1.10.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.5.0_HOME>/repository/components/dropins directory.

  9. If you manually added any JAR files to the <API-M_1.10.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.5.0_HOME>/repository/components/lib directory.

Step 2 - Upgrade API Manager to 2.5.0

  1. Stop all running WSO2 API Manager server instances.
  2. Make sure you backed up all the databases and synapse configs as instructed in step 1 of the previous section.

  3. Before you run the migration client, open the <API-M_2.5.0_HOME>/repository/conf/datasources/master-datasources.xml file, and set the <username>, and <password> elements of the AM_DB JNDI to that of a user who has permissions to alter tables in the database.

    Tip: After you are done running the migration client, you can switch these credentials back to a user with lesser privileges.

    For example,

    <datasource>
            ...
            <definition type="RDBMS">
                <configuration>
                    ...
                    <username>xxxxxx</username>
                    <password>xxxxxx</password>
                    ...
                </configuration>
             </definition>
    </datasource>
  4. Upgrade the Identity component in WSO2 API Manager from version 5.1.0 to 5.2.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the migration DB scripts for version 5.1.0 to 5.2.0 from here.
    2. Unzip and find the correct DB script in the wso2is-5.2.0-migration/dbscripts/identity/migration-5.1.0_to_5.2.0 directory.
    3. Manually execute the DB scripts that correspond to the RDBMS that you are working with.

      Apply the respective DB script found inside the following directories against the respective DB as follows:

      DB script directoryApplicable DBDescription
      wso2is-5.2.0-migration/dbscripts/identity/migration-5.1.0_to_5.2.0 AM_DB
      wso2is-5.2.0-migration/dbscripts/migration-5.1.0_to_5.2.0 UM_DBThis script includes insert operations and some index creation scripts against the UM_CLAIM table, which are required in order for you to upgrade from your previous API-M version to API-M 2.0.0.

      For example, if you are working with a MySQL DB, run the mysql.sql script.

  5. Download and extract the WSO2 API Manager migration client and do the following to upgrade your version of WSO2 API Manager to 2.0.0:

    This migration client upgrades WSO2 API Manager components from 1.10.0 to version 2.0.0 first. Then from step 6 onwards, we carryout the rest of the changes required to upgrade from version 2.0.0 to 2.5.0.

    1. Copy the org.wso2.carbon.apimgt.migrate.client-2.0.X.jar file to the <API-M_2.5.0_HOME>/repository/components/dropins directory. If you use a clustered/distributed API Manager setup, copy the JAR file to the Publisher and Gateway nodes.
    2. Copy the migration-script folder into <API-M_2.5.0_HOME>. If you use a clustered/distributed API Manager setup, copy the migration-script folder to a Publisher node.
      1. Start API Manager 2.5.0 with the following command-line options to migrate the database, registry, and the file system, separately, in the given order.

        DescriptionCommand
        To migrate the database only. This migrates the AM_DB database. Please ensure that the <API_M_PUBLISHER>/repository/conf/datasources/master-datasources.xml file has an entry for AM_DB.-DmigrateDB=true -Dcomponent=apim -DmigrateFromVersion=1.10.0
        To migrate the registry only. This migrates the registry-related resources such as .rxt and swagger definitions.-DmigrateReg=true -Dcomponent=apim -DmigrateFromVersion=1.10.0
        To migrate the file system only. This migrates the synapse config files such as APIs that reside in the file system. Therefore, you must run this command on the Gateway node/s of a distributed API Manager setup.-DmigrateFS=true -Dcomponent=apim -DmigrateFromVersion=1.10.0

        To migrate to the new throttling engine and generate throttle policies. This migrates synapse config files, the API-M database with new throttle policies and generates throttle policies to the <API-M_HOME>/executionplans directory. Therefore, you must run this command against a node that has synapse config files and the AM_DB. After the migration, copy the <API-M_HOME>/executionplans directory to the repository/deployment/server/executionplans directory of the Traffic Manager node.

        -Dcomponent=apim -DmigrateFromVersion=1.10.0 -Doptions=migrateThrottling

        If you are using a clustered/distributed API Manager setup, run with the following options -DmigrateDB=true -DmigrateReg=true -Dcomponent=apim -DmigrateFromVersion=1.10.0 in the API Publisher node and the -DmigrateFS=true -Dcomponent=apim -DmigrateFromVersion=1.10.0 options in the API Gateway node.

        Troubleshooting

        If you have enabled token encryption in your database, those consumer keys need to be decrypted as part of the database migration. If you see the error below, it means that the migration client has failed to decrypt some of the keys in the old database.
        ERROR {org.wso2.carbon.apimgt.migration.client.MigrateFrom19to110} -  Cannot decrypt consumer key : DRHbt68uSU4+7xtCEIzuf42CMaqXbNjYl3OYVJ0VL/H6EsFo8GBRaZGUhLHlTWIHzYrvoeOpb1YbauvRRIN/b6VqEd9m8HuYOIuLkkDd AM_APPLICATION_KEY_MAPPING table {org.wso2.carbon.apimgt.migration.client.MigrateFrom19to110}

        If this error occurs, by default, the migration client will terminate without updating databases in order to maintain database integrity. However, you can change this behavior by adding the following argument and running the API-M migration client again from the beginning. Please note that the database is then updated with the keys where decryption was successful and failed keys are permanently deleted.
        -DremoveDecryptionFailedKeysFromDB=true

        Expected Errors

        The following are some errors that you may come across. Do not get alarmed as these errors are to be expected, since you are yet to complete the migration process.

        • You may notice the following exception being thrown in the console when API Manager 2.5.0 is started at this point,

          org.wso2.carbon.idp.mgt.IdentityProviderManagementException: Error occurred while retrieving Identity Provider information for tenant : carbon.super and Identity Provider name : LOCAL

          This is due to the fact that the IDP_METADATA table does not exist in the API Manager database. The instructions given from step 9 onwards address the creation of the IDP_METADATA table after which this exception will no longer be thrown.

        • You may notice the following error during the first stage of running the WSO2 API Manager Migration Client.

          com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.AM_POLICY_APPLICATION' doesn't exist

          This error will get resolved after the first run of the migration client.

        • You may notice Gateway artifact deployment related errors.
          The following is one such exception that is thrown in the console when WSO2 API Manager 2.5.0 is started at this point.

          Error loading class : org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler - Class not found

          This error gets eliminated after executing the Gateway artifact migration script in step 6 .

        • You may also notice the following exception when WSO2 API Manager 2.5.0 is started at this point.

          com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.IDN_CLAIM_DIALECT' doesn't exist

          This error will be resolved after following the instructions given under step 9 below.

  6. Run the respective migration script, based on your environment. 

    Run the apim200_to_apim250_gateway_artifact_migrator.sh  script, as shown below, to migrate from API Manager 2.0.0 to 2.5.0. 

    ./apim200_to_apim250_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.0.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.5.0_HOME>/repository/tenants

    Where, <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0. 

    Run the PowerShell script apim200_to_apim250_gateway_artifact_migrator.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim200_to_apim250_gateway_artifact_migrator.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.0.0 deployment, reside.

    • Super Tenant - <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    Run the PowerShell script apim200_to_apim250_gateway_artifact_migrator_for_tenants.ps1 as follows:

    a. Open a Windows command prompt and type the following command.

    powershell

    A message about PowerShell appears, and the shell changes to PS.

    b. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

    .\apim200_to_apim250_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.5.0 API definitions, which are copied from the API-M 2.0.0 deployment, reside.

    • Tenants - <API-M_2.5.0_HOME>/repository/tenants

    Where <API-M_2.5.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.5.0.

    It may take a considerable amount of time, proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim200_to_apim250_gateway_artifact_migrator.ps1 / apim200_to_apim250_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim200_to_apim250_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal/command-line as the Administrator.

    Set-ExecutionPolicy RemoteSigned
  7. Upgrade the API Manager database from version 2.0.0 to version 2.5.0.

    1. Download the apimgt-db-migration-scripts-2.0to2.5.zip and extract it.

    2. Execute the relevant database script on WSO2AM_DB from the scripts provided in the extracted directory.

  8. Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.6.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the wso2is-5.x.x-migration.zip and extract it.
    2. Copy the migration-resources folder in the extracted folder to <API-M_2.5.0_HOME>.
    3. Open the migration-config.yaml file in the migration-resources directory and edit the currentVersion element to 5.2.0, as shown below.

      migrationEnable: "true"
      
      currentVersion: "5.2.0"
      migrateVersion: "5.6.0"

      Make sure you have enabled migration by setting the migrationEnable element to true.

    4. Remove the following entries from the migration-config.yaml file.

         -
          name: "EventPublisherMigrator"
          order: 11

      and

         -
          name: "ChallengeQuestionDataMigrator"
          order: 5
          parameters:
            schema: "identity"
    5. From the extracted folder, copy the org.wso2.carbon.is.migration-5.6.0.jar to the <API-M_2.5.0_HOME>/repository/components/dropins directory.

    6. Copy and replace the keystores used in the previous version to the <API-M_2.5.0_HOME> / repository/resources/security directory.

    7. Start API Manager 2.5.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

    8. After you have successfully completed the migration, stop the server and remove the following files and folders.

      • Remove the org.wso2.carbon.is.migration-5.6.0.jar file, which is in the <API-M_2.5.0_HOME>/repository/components/dropins directory.

      • Remove the migration-resources directory, which is in the <API-M_2.5.0_HOME> directory.

      • If you ran WSO2 API-M as a Windows Service when doing the identity component migration, then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity

  9. You have to run the following migration client for migrating Access Control support for API Publisher because Publisher Access Control is enabled by default in API Manager 2.5.0.

    1. Download  the Access Control Migration Client from here  and copy it to the  <API-M_HOME>/repository/components/dropins  directory.

    2. Start the server with -DmigrateAccessControl=true as follows.

      sh wso2server.sh -DmigrateAccessControl=true
  10. Add the following property to <API-M_HOME>/repository/conf/user-mgt.xml file under <AuthorizationManager> as follows.

    <AuthorizationManager class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">
    	...
    	<Property name="PreserveCaseForResources">false</Property>
    </AuthorizationManager>
  11. Re-index the artifacts in the registry.

    1. Shut down WSO2 API Manager 2.5.0 (if you have already started it).

    2. Run the reg-index.sql script against the REG_DB database.

    3. Add the tenantloader-1.0.jar to <API-M_2.5.0_HOME>/repository/components/dropins directory

    4. Rename the <lastAccessTimeLocation> element in the <API-M_2.5.0_HOME>/repository/conf/registry.xml file.

    5. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    6. If the <API-M_2.5.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    7. Start the WSO2 API-M server.
    8. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.5.0_HOME>/repository/components/dropins directory.

Step 3 - Migrate the statistics related data from WSO2 DAS to API Manager Analytics

This step is required only if you have WSO2 DAS configured in your current deployment for analytics.

From WSO2 API Manager 2.0.0 onwards, statistics can be configured only for RDBMS since the API Manager 1.10.0 REST based analytic configuration no longer exists. This section walks you through how to migrate statistics data from previous versions of API Manager to 2.5.0. 

If you have configured analytics using RDBMS,

  1. Take a backup of the API Manager statistics DB. 
  2. Add the API Manager statistics DB as a datasource in WSO2 API Manager Analytics.

If you configured analytics using the REST client in API-M 1.10.0 with DAS 3.0.x,

  1. Configure analytics using API Manager 1.10.0 and DAS 3.0.x with the RDBMS client, according to the instructions in Publishing API Runtime Statistics Using RDBMS.
  2. Wait for data to appear on the RDBMS and API Manager statistics dashboard.
  3. Replace the Statistics DB (STAT_DB) configurations configured in WSO2 DAS for API Manager 1.10.0, in the
    <API-M_ANALYTICS_2.5.0_HOME>/repository/conf/stats-datasources.xml file.

Finally, execute the relevant db script found in migration-scripts/110-200-migration/stat/ on the STAT_DB.

Once done, configure analytics in API Manager 2.5.0 according to the instructions in Configuring APIM Analytics.

Step 4 - Start the WSO2 API-M server

sh wso2server.sh

wso2server.bat


This concludes the upgrade process.

Tip 1: The migration client that you use in this guide automatically migrates your tenants, workflows, external user stores, etc. to the upgraded environment. There is no need to migrate them manually.

Tip 2: If you are using an SVN based deployment synchronizer, start with a clean SVN repository and point the new deployment nodes to the new SVN repository. Also, any existing .svn directories in the new deployment's <API-M_2.5.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.5.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

Follow the instructions below to upgrade your WSO2 API Manager server from APIM 1.8.0/1.9.0/1.9.1 to 2.5.0

If you are using WSO2 IS as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Upgrade WSO2 API Manager to 2.0.0

It is not possible to directly upgrade from WSO2 API Manager 1.8.0/1.9.0/1.9.1 to 2.5.0.

Upgrade your current WSO2 API-M version (1.8.0/1.9.0/1.9.1) to WSO2 API-M 2.0.0.

Step 2 - Upgrade WSO2 API Manager to 2.5.0

After you have successfully migrated your current WSO2 API-M version to 2.0.0, upgrade from API-M 2.0.0 to API-M 2.5.0. For more information, click below:

Upgrading from API-M 2.0.0 to API-M 2.5.0

This concludes the upgrade process.

  • No labels