Many 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
- 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. - 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. - 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
. - 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.
-
- Copy the
org.wso2.carbon.apimgt.migrate.client-2.0.X.jar
file to the$APIM210/repository/components/dropins
directory. - Copy the migration-script folder into $APIM210 directory.
- 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.
- 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.
- 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.
- 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.
- Copy the
- 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
- 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.
- Remove
$APIM210/solr
directory - Update WSO2 API Manager database against AM_DB using upgrade from WSO2 Integrity Server 5.1.0 to 5.2.0
- Download 1.0 to 5.2.0 migration DB scripts and unzip it.
- Execute the corresponding database script against the AM_DB database manually.
use wso2am_db; source /tmp/migrationscripts/mysql.sql;
- Update WSO2 API Manager database against AM_DB using upgrade from WSO2 Integrity Server 5.2.0 to 5.3.0
- Download 2.0 to 5.3.0 migration DB scripts and unzip it.
- 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
|
Start WSO2 API Manager
- After you are done running the migration client, you can switch database credentials back to a user with lesser privileges.
- Start WSO2 API Manager 2.1.0
If the JDBC exceptions likecom.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.
|
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.