fb
API Management 7 minutes

Migrating WSO2 API Manager 1.10.0 to 2.1.0

ThomasZielinski.jpg
Thomas Zielinski
Java Developer
API Manager witruimte
Scroll

wso2-api-manager.pngMany customers have to make a decision if they have to migrate their product to the newest version. In this case the management takes questions like this in to consideration:

  • Why migrate, if the current product is running and working?
  • Why migrate, if our customers are using the product without any problems?
  • Why migrate, if we will not use any of the new features?
  • What benefits are in the newest version?
  • Is the newest version stable?
  • How much time do we need to migrate?
  • What would be the impact on our customers?
  • What do we have to test?

There is no simple answer. From the management point of view the company should have some budget, resources and time slots for this operation. In this case, many companies defer this operation’s term indefinitely. From the perspective of other people (administrator, developer, user or customer) update to a new version is a benefit if:

  • all bugs from previous versions are fixed
  • the new version is more stable than the previous one
  • the new version contains new features
  • the new features give more possibilities to the customer

Migration

In this article, we would like to estimate how much time is needed to migrate WSO2 API Manager and describe the steps to update WSO2 API Manager 1.10.0 version to WSO2 API Manager 2.1.0. We describe the process on the API Manager standalone installation (without tenants) using the RDBMS.

Backup

Database backup

During the migration process the WSO2 API Manager database is changed. In this case the database backup is needed. The databases defined in
$APIM1100/repository/conf/datasources/master-datasources.xml and $APIM1100/repository/conf/datasources/metrics-datasources.xml have to be exported.

$ mysqldump --databases WSO2_AM_DB WSO2_APIM_DB WSO2_METRICS_DB WSO2_REG_APIM_DB WSO2_STATS_DB WSO2_USER_DB > /opt/wso2/dumps/wso2am.1.10.0.dump.sql

API Manager 1.10 backup

Archive the API Manager v1.10

$ tar cvfz /opt/wso2/dumps/wso2am.1.10.0.tgz /opt/wso2/wso2am-1.10.0

API Manager 2.1.0

Installation

Download and install WSO2 API Manager 2.1.0.

Setup

  1. Setup the $APIM210/repository/conf/datasources/master-datasources.xml and $APIM210/repository/conf/datasources/metrics-datasources.xml, similar to the configuration of the API Manager 1.10.0. For an upgrade process needs the database user who has the permissions to alter data tables.
  2. Setup the registry configurations in the file $APIM210/repository/config/registry.xml and the user database in the file $APIM210/repository/conf/user-mgt.xml, similar to the configurations of the current API Manager.
  3. Move all your synapse configurations from directory $APIM1100/repository/deployment/server/synapse-config/default, except the files listed below:
    /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
    by copying and replacing the files to the $APIM210/repository/deployment/server/synapse-config/default.
  4. 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.
    1. Copy the org.wso2.carbon.apimgt.migrate.client-2.0.X.jar file to the $APIM210/repository/components/dropins directory.
    2. Copy the migration-script folder into $APIM210 directory.
    3. Migrate the database only.  This step migrates the AM_DBdatabase, in this case ensure the $APIM210/repository/conf/datasources/master-datasources.xml file has entry AM_DB.
      > $APIM210/bin/wso2server.sh -DmigrateDB=true -Dcomponent=apim -DmigrateFromVersion=1.10.0

      After the WSO2 API starts, stop it.

    4. Migrate the registry only. This step migrates the registry-related resources such as .rxt and swagger definitions
      > $APIM210/bin/wso2server.sh -DmigrateReg=true -Dcomponent=apim -DmigrateFromVersion=1.10.0

      After the WSO2 API starts, stop it.

    5. Migrate the file system only. This step migrates the synapse config files such as APIs that reside in the file system.
      > $APIM210/bin/wso2server.sh -DmigrateFS=true -Dcomponent=apim -DmigrateFromVersion=1.10.0

      After the WSO2 API starts, stop it.

    6. To migrate to the new throttling engine and generate throttle policies. This migrates synapse config files, the API Manager database with new throttle policies and generates throttle policies to the $APIM210/executionplans
      > $APIM210/bin/wso2server.sh –Doptions=migrateThrottling -Dcomponent=apim -DmigrateFromVersion=1.10.0

      After the WSO2 API starts, stop it and copy the $APIM210/executionplans directory to the $APIM210/repository/deployment/server/executionplans directory.

  1. Run the  apim200_to_apim210_gateway_artifact_migrator.sh   script as shown below to migrate from API Manager 2.0.0 to 2.1.0.
    > ./apim200_to_apim210_gateway_artifact_migrator.sh $APIM210/repository/deployment/server/synapse-configs/default
  1. Rename the value of <lastAccessTimeLocation> element in the $APIM210/repository/conf/registry.xml file to re-index the artifacts in the registry. For example, change the value /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1.
  2. Remove $APIM210/solr directory
  3. Update WSO2 API Manager database against AM_DB using upgrade from WSO2 Integrity Server 5.1.0 to 5.2.0
    1.  Download 1.0 to 5.2.0 migration DB scripts and unzip it.
    2. Execute the corresponding database script against the AM_DB database manually.
      use wso2am_db; source /tmp/migrationscripts/mysql.sql;
  1. Update WSO2 API Manager database against AM_DB using upgrade from WSO2 Integrity Server 5.2.0 to 5.3.0
    1. Download 2.0 to 5.3.0 migration DB scripts and unzip it.
    2. Execute the corresponding database script against the AM_DB database manually.
      use wso2am_db; source /tmp/migrationscripts/mysql.sql;
During the steps 4-9 in the log file wso2carbon.log of the WSO2 API Manager 2.1.0 can occurs the exceptions:

com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Invalid default value for 'UPDATED_TIME'
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table

'wso2_am_db.am_policy_application' doesn't exist
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
org.wso2.carbon.apimgt.api.APIManagementException: Failed to check is exist:
50PerMin--1234
       at
org.wso2.carbon.apimgt.impl.dao.ApiMgtDAO.handleException(ApiMgtDAO.java:6555)
Caused by: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'wso2_am_db.am_policy_application' doesn't exist
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
org.wso2.carbon.identity.claim.metadata.mgt.exception.ClaimMetadataException: Error
while listing claim dialects
Caused by: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'wso2_am_db.idn_claim_dialect' doesn't exist
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
org.wso2.carbon.identity.claim.metadata.mgt.exception.ClaimMetadataException: Error while listing claim dialects
Caused by: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'wso2_am_db.idn_claim_dialect' doesn't exist
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
java.lang.ClassNotFoundException: org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler cannot be found by synapse-core_2.1.7.wso2v10
org.apache.synapse.SynapseException: Error loading class : org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler - Class not found
Caused by: java.lang.ClassNotFoundException: org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler cannot be found by synapse-core_2.1.7.wso2v10
java.lang.ClassNotFoundException: org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler cannot be found by synapse-core_2.1.7.wso2v10
org.apache.synapse.SynapseException: Error loading class : org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler - Class not found
Caused by: java.lang.ClassNotFoundException: org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler cannot be found by synapse-core_2.1.7.wso2v10
org.apache.synapse.deployers.SynapseArtifactDeploymentException: API deployment from the file : /Users/thomas/yenlo/installs/migration/wso2am-2.1.0/repository/deployment/server/synapse-configs/default/api/admin--cars-api_v0.0.1.xml : Failed.

Ignore them. The exceptions should disappear after the all installation steps.

Start WSO2 API Manager

  1. After you are done running the migration client, you can switch database credentials back to a user with lesser privileges.
  2. Start WSO2 API Manager 2.1.0
If the JDBC exceptions like

com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'wso2_am_db.am_block_conditions' doesn't exist
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'wso2_am_db.am_policy_global' doesn't exist
        at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:943)
will occurs during starting WSO2 API Manager 2.1.0, then stop it and run manually DB script from migration-script/110-200-migration against AM_DB.

use wso2am_db; source $APIM210/ migration-scripts/110-200-migration/mysql.sql;

Time estimation

Step Estimation
Copy of the product and database 0.5-3h
Migrating the configurations 0.5-2h
Upgrade API Manager to v2.1 0.5-4h

The time of the migration from API Manager 1.10 to 2.1.0, depends on the size of thedatabase. During testing the migration process, we need about 1 hour to finish it. The realistic time for the upgrade is 1 working day.

Conclusion

The migration process is not complicated. The operator need to follow the steps described in this article or WSO2 manual. Upgrading from the Previous Release, which contains more information (i.e. for distributed/clustered setup).

There is no need to write additional tests for the API Manager components or APIs. The APIs can be tested with previous integration tests.

The most important thing is that defined APIs do not need to be resubscribed by the users/customers. They can use it immediately without any additional action.