The following information describes how to upgrade your WSO2 API Manager server (WSO2 API-M) from APIM 1.8.0/1.9.0/1.9.1/1.10.0/2.0.0/2.1.0/2.2.0/2.5.0 to 2.6.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, in order to use this version in your production environment, use the WSO2 Update Manager and get the latest available updates for WSO2 API Manager 2.6.0. For more information on how to do this, see Updating WSO2 Products.
Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.5.0 to 2.6.0.
If you are using WSO2 Identity Server (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 WSO2 API-M 2.5.0 configurations
Do not copy entire configuration files from the current version of WSO2 API Manager to the new one, as some configuration files (e.g., api-manager.xml
) may have changed. Instead, redo the configuration changes in the new configuration files.
Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.
Back up all databases in your API Manager instances along with the Synapse configurations of all the tenants and the super tenant.
The Synapse configurations of the super tenant are in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory.The Synapse configurations 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.
- Download API Manager 2.6.0 from https://wso2.com/api-management/.
Open the
<API-M_2.6.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 that you are already using.- User Store
- Registry database/s
- API Manager databases
- Statistics database (If statistics are configured)
Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the
defaultAutoCommit
property is set totrue
by default for the following datasource configurations in themaster-datasources.xml
file.- WSO2_CARBON_DB
- WSO2AM_DB
- WSO2AM_STATS_DB
When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.
Edit the registry configurations in the
<API-M_2.6.0_HOME>/repository/conf/registry.xml
file and the user database in the<API-M_2.6.0_HOME>/repository/conf/user-mgt.xml
file, similar to the configurations of the current WSO2 API Manager.If you are working with a clustered/distributed API Manager setup, follow step 5 on the Gateway node.
- Move all your Synapse configurations to API-M 2.6.0 pack.
- Move your Synapse super tenant configurations.
Copy the contents in the<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory and replace the contents in the<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
directory with the copied contents. - Move all your tenant Synapse configurations.
Copy the contents in the<CURRENT_API-M_HOME>/repository/tenants
directory and replace the contents in the<API-M_2.6.0_HOME>/repository/tenants
directory with the copied contents.
- Move your Synapse super tenant configurations.
- If you manually added any custom OSGI bundles to the
<API-M_2.5.0_HOME>/repository/components/dropins
directory, copy those to the<API-M_2.6.0_HOME>/repository/components/dropins
directory. - If you manually added any JAR files to the
<API-M_2.5.0_HOME>/repository/components/lib
directory, copy those and paste them in the<API-M_2.6.0_HOME>/repository/components/lib
directory.
Step 2 - Upgrade WSO2 API-M 2.5.0 to 2.6.0
- Stop all WSO2 API Manager server instances that are running.
Make sure you backed up all the databases and Synapse configurations as instructed in step 1 of the previous section.
Upgrade the WSO2 API Manager database from version 2.5.0 to version 2.6.0.
Download
apimgt-db-migration-scripts-2.5to2.6.zip
and extract it.- Execute the relevant database script, from the scripts that are provided in the extracted directory, on the
WSO2AM_DB
database.
Upgrade the Identity component in WSO2 API Manager from version 5.6.0 to 5.7.0.
As WSO2 API-M shares identity components with WSO2 Identity Server (WSO2 IS), this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).
- Download the identity component migration resources and unzip it to a local directory.
Navigate to the latest release tag and download thewso2is-migration-x.x.x.zip
under Assets. - Copy the
migration-resources
folder from the extracted folder to the<API-M_2.6.0_HOME>
directory. Open the
migration-config.yaml
file in the migration-resources directory and make sure that thecurrentVersion
element is set to 5.6.0, as shown below.migrationEnable: "true" currentVersion: "5.6.0" migrateVersion: "5.7.0"
Make sure you have enabled migration by setting the
migrationEnable
element totrue
as shown above.Copy the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
from the extracted folder to the<API-M_2.6.0_HOME>
/repository/components/dropins
directory.Copy the keystores (i.e.,
client-truststore.jks
,wso2cabon.jks
and any other custom JKS) used in the previous version and replace the existing keystores in the<API-M_2.6.0_HOME>/repository/resources/security
directoryStart WSO2 API Manager 2.6.0 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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.
Troubleshooting
When running the above step if you encounter the following error message, follow the steps in this section. Note that this error could occur only if the identity tables contain a huge volume of data.
Sample exception stack traceERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} - Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; lastwait:60000
1. Change the value in
<indexingFrequencyInSeconds>
in<API-M_HOME>/repository/conf/registry.xml
file to a higher value (e.g., 10)2. Re-run the command above.
Make sure to revert the change done in Step 1, after the migration is complete.
After you have successfully completed the migration, stop the server and remove the following files and folders.
Remove the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
file, which is in the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Remove the
migration-resources
directory, which is in the<API-M_2.6.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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
- Download the identity component migration resources and unzip it to a local directory.
- Re-index the artifacts in the registry.
Run the reg-index.sql script against the
REG_DB
database.Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.
- Add the
tenantloader-1.0.jar
to<API-M_2.6.0_HOME>/repository/components/dropins
directory - Rename the
<lastAccessTimeLocation>
element in the<API-M_2.6.0_HOME>
/repository/conf/registry.xml
file. - 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
- If the
<API-M_2.6.0_HOME>/
solr
directory exists, take a backup and thereafter delete it. - Start the WSO2 API-M server.
- Stop the WSO2 API-M server and remove the
tenantloader-1.0.jar
from the<API-M_2.6.0_HOME>/repository/components/dropins
directory.
Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.5.0 configurations to 2.6.0
This step is only required if you have WSO2 API-M-Analytics configured in your current deployment.
Before you procceed with the WSO2 API-M Analytics migration do the following, if you have already not done the configuration changes as mentioned in Step 1.
Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml
file and the user database configurations in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml
file so that the configurations are similar to the configurations of the current WSO2 API Manager.
Follow the steps below to migrate APIM Analytics 2.5.0 to APIM Analytics 2.6.0
Step 3.1 - Configure WSO2 API-M Analytics 2.6.0
Download the WUM updated pack for WSO2 API Manager Analytics 2.6.0.
Note that it is mandatory to use a WUM updated WSO2 API Manager Analytics 2.6.0 pack when migrating the configurations for WSO2 API-M Analytics.
Create a new database for the new statistics database and configure it in the
<API-M_ANALYTICS_2.6.0_HOME>/conf/worker/deployment.yaml
as follows:
In this example shows to configure MySQL database configurations.- name: APIM_ANALYTICS_DB description: "The datasource used for APIM statistics aggregated data." jndiConfig: name: jdbc/APIM_ANALYTICS_DB definition: type: RDBMS configuration: jdbcUrl: 'jdbc:mysql://localhost:3306/spDatabase?autoReconnect=true' username: username password: password driverClassName: com.mysql.jdbc.Driver maxPoolSize: 50 idleTimeout: 60000 connectionTestQuery: SELECT 1 validationTimeout: 30000 isAutoCommit: true
In previous versions of WSO2 API-M, even though the
defaultAutoCommit
value was set tofalse
in theSTAT_DB
, when performing Analytics migration in WSO2 API-M Analytics 2.6.0, you need to set theisAutoCommit
value totrue
in theAPIM_ANALYTICS_DB
datasource configuration.- Copy the relevant JDBC driver to the
<APIM_ANALYTICS_2.6.0_HOME>/lib
folder. Start the new API-M Analytics server.
cd <APIM_ANALYTICS_2.6.0_HOME>/bin sh worker.sh
When the WSO2 API-M Analytics 2.6.0 server starts, the new statistics tables will get generated in the database that you configured in step 3.1 - (2.) above.
Step 3.2 - Configure WSO2 API-M 2.6.0 for Analytics
Follow the instructions below to configure WSO2 API Manager for the WSO2 API-M Analytics migration in order to migrate the statistics related data.
Configure the statistics related datasources for WSO2 API Manager Analytics.
Configure the following 3 datasources in the<API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml
file.The following 3 datasources should be configured in the
<API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml
file only until the stats migration is complete . After the statistics migration is complete remove theAPIM_ANALYTICS_DB
datasource configuration, which was added for the new statistics database, from the latter mentioned file.The following in an example of how the configurations should be defined when using MySQL.
The first datasource points to the previous API-M version's AM_DB datasource.
<datasource> <name>WSO2AM_DB</name> <description>The datasource used for API Manager database</description> <jndiConfig> <name>jdbc/WSO2AM_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://localhost:3306/AM_DB?autoReconnect=true</url> <username>username</username> <password>password</password> <defaultAutoCommit>true</defaultAutoCommit> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
The second datasource points to the WSO2 Data Analytics (WSO2 DAS) based previous datasource WSO2AM_STATS_DB for statistics.
<datasource> <name>WSO2AM_STATS_DB</name> <description>The datasource used for getting statistics to API Manager</description> <jndiConfig> <name>jdbc/WSO2AM_STATS_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://localhost:3306/dasDatabase?autoReconnect=true</url> <username>username</username> <password>password</password> <defaultAutoCommit>true</defaultAutoCommit> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
The third datasource points to the WSO2 Stream Processor (WSO2 SP) based new datasource APIM_ANALYTICS_DB for statistics.
<datasource> <name>APIM_ANALYTICS_DB</name> <description>The datasource used for getting statistics to API Manager for APIM 2.6.0</description> <jndiConfig> <name>jdbc/APIM_ANALYTICS_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://localhost:3306/spDatabase?autoReconnect=true</url> <username>username</username> <password>password</password> <defaultAutoCommit>true</defaultAutoCommit> <driverClassName>com.mysql.jdbc.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
- Download and extract the WSO2 API Manager migration client and carry out the following steps to upgrade to WSO2 API Manager Analytics 2.6.0.
- Copy the migrate.client-2.6.x-2.jar to the
<API-M_2.6.0_HOME>/repository/components/dropins
folder. - Copy the relevant JDBC driver to the
<API-M_2.6.0_HOME>/repository/components/lib
folder. Make sure that WSO2 API-M Analytics is disabled in the
<API-M_2.6.0_HOME>/repository/conf/
api-manager.xml
file.<Analytics> <Enabled>false</Enabled> ... <Analytics>
After setting the above configurations in place, start up the WSO2 API-M 2.6.0 server with the following commands.
cd <API-M_2.6.0_HOME>/bin sh wso2server.sh -DmigrateStats=true
Table-wise Migration
The migration client provides the support for table-wise migration.
The following are the table names that needs to be migrated.
ApiPerDestinationAgg,ApiResPathPerApp,ApiVersionPerAppAgg,ApiLastAccessSummary,ApiFaultyInvocationAgg,ApiUserBrowserAgg,GeoLocationAgg,ApiExeTimeDay,ApiExeTimeHour,ApiExeTimeMinute,ApiThrottledOutAgg,APIM_ReqCountAgg,ApiUserPerAppAgg
You need to use the
statTable
migration property for table wise migration.For example, if you need to migrate only the
ApiPerDestinationAgg
andApiResPathPerApp
tables use the following command:When you need to migrate multiple tables, the comma separated table names should without spaces before or after the comma as shown below.
sh wso2server.sh -DmigrateStats=true -DstatTable=ApiPerDestinationAgg,ApiResPathPerApp
If the default 3 datasource names/name, which you specified above, changed from the details that you specified in the
<API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml
file. Use the following command to pass the values to the migration client.sh wso2server.sh -DdataSource=<AM_DATASOURCE_NAME>,<OLD_STAT_DATASOURCE_NAME>,<NEW_STAT_DATASOURCE_NAME>
sh wso2server.sh -DdataSource=jdbc/WSO2AM_DB,jdbc/WSO2AM_STATS_DB,jdbc/APIM_ANALYTICS_DB
The following warning message could occur during migration if the relevant consumer key does not exist in the
AM_APPLICATION_KEY_MAPPING
table due to Application deletion.ConsumerKey <consumerKey> does not contain in the AM_APPLICATION_KEY_MAPPING table.
In such scenarios, you will face a migration data loss due to API or Application deletion.
- Stop the WSO2 API-M server and remove the migration JAR copied under Step 3.2 - (3.) above.
- Remove both the old and new
STAT_DB
datasources from the<API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml
file, which you defined in step 3.2 - (1.). Enable analytics in WSO2 API-M by setting the following configuration to true in the
<API-M_2.6.0_HOME>/repository/conf/
api-manager.xml
file.<Analytics> <Enabled>true</Enabled> ... <Analytics>
Restart the WSO2 API-M Server.
cd <API-M_2.6.0_HOME>/bin sh wso2server.sh
Step 4 - Start the WSO2 API-M 2.6.0 server
sh wso2server.sh
wso2server.bat
Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.2.0 to 2.6.0.
If you are using WSO2 Identity Server (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 WSO2 API-M 2.2.0 configurations
Do not copy entire configuration files from the current version of WSO2 API Manager to the new one, as some configuration files (e.g., api-manager.xml
) may have changed. Instead, redo the configuration changes in the new configuration files.
Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.
Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.
The Synapse configs of the super tenant are in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory.The 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.
- Download WSO2 API Manager 2.6.0 from https://wso2.com/api-management/.
Open the
<API-M_2.6.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 WSO2 API Manager instance already being used.- User Store
- Registry database/s
- API Manager databases
Statistics database (If statistics are configured)
Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the
defaultAutoCommit
property is set totrue
by default for the following datasource configurations in themaster-datasources.xml
file.- WSO2_CARBON_DB
- WSO2AM_DB
- WSO2AM_STATS_DB
When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.
Edit the registry configurations in the
<API-M_2.6.0_HOME>/repository/conf/registry.xml
file and the user database in the<API-M_2.6.0_HOME>/repository/conf/user-mgt.xml
file, similar to the configurations of the current API Manager.If you are working with a clustered/distributed API Manager setup, follow step 5 on the Gateway node.
- Move all your Synapse configurations to API-M 2.6.0 pack.
- Move your Synapse super tenant configurations.
Copy the contents in the<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory and replace the contents in the<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
directory with the copied contents. - Move all your tenant Synapse configurations.
Copy the contents in the<CURRENT_API-M_HOME>/repository/tenants
directory and replace the contents in the<API-M_2.6.0_HOME>/repository/tenants
directory with the copied contents.
- Move your Synapse super tenant configurations.
- 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.6.0_HOME>/repository/components/dropins
directory. - 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.6.0_HOME>/repository/components/lib
directory.
Step 2 - Upgrade WSO2 API-M 2.2.0 to 2.6.0
- Stop all WSO2 API Manager server instances that are running.
Make sure you backed up all the databases and Synapse configs, as instructed in step 1 of the previous section.
To start the migration process, run the respective migration script based on your environment.
Run the
apim220_to_apim260_gateway_artifact_migrator.sh
script, as shown below, to migrate from WSO2 API Manager 2.2.0 to 2.6.0../apim220_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were 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.6.0_HOME>/repository/deployment/server/synapse-configs/default
Tenant -
<API-M_2.6.0_HOME>/repository/tenants
Where,
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0
.Run the PowerShell script
apim220_to_apim260_gateway_artifact_migrator.ps1
as shown below, to migrate from WSO2 API Manager 2.2.0 to 2.6.0.Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowserShell (PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim220_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.2.0 deployment, reside.Super Tenant -
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
Run the PowerShell script
apim220_to_apim260_gateway_artifact_migrator_for_tenants.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowerShell (PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim220_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.2.0 deployment, reside.Tenants -
<API-M_2.6.0_HOME>/repository/tenants
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
It may take a considerable amount of time, which is proportionate to the amount of artifacts, to complete the migration process.
Troubleshooting
Why do I get the following error - apim220_to_apim260_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_apim260_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
Upgrade the API Manager database from version 2.2.0 to version 2.6.0.
Download
apimgt-db-migration-scripts-2.2to2.6.zip
and extract it.- Execute the relevant database script, from the scripts that are provided in the extracted directory, on the
WSO2AM_DB
database.
Upgrade the Identity component in WSO2 API Manager from version 5.5.0 to 5.7.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).
- Download the identity component migration resources and unzip it to a local directory.
Navigate to the latest release tag and download thewso2is-migration-x.x.x.zip
under Assets. - Copy the
migration-resources
folder from the extracted folder to the<API-M_2.6.0_HOME>
directory. Open the
migration-config.yaml
file in the migration-resources directory and make sure define thecurrentVersion
element to 5.5.0, as shown below.migrationEnable: "true" currentVersion: "5.5.0" migrateVersion: "5.7.0"
Make sure you have enabled migration by setting the
migrationEnable element to true as shown above.
Copy the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
from the extracted folder to the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Copy the keystores (i.e.,
client-truststore.jks
,wso2cabon.jks
and any other custom JKS) used in the previous version and replace the existing keystores in the<API-M_2.6.0_HOME>/repository/resources/security
directory.Start WSO2 API Manager 2.6.0 via the terminal 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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.
Troubleshooting
When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.
Sample exception stack traceERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} - Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; lastwait:60000
1. Change the value in <indexingFrequencyInSeconds> in
<API-M_HOME>/repository/conf/registry.xml
to a higher value (e.g., 10)2. Re-run the command above.
Make sure to revert the change done in Step 1 , after the migration is complete
After you have successfully completed the migration, stop the server and remove the following files and folders.
Remove the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
file, which is in the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Remove the
migration-resources
directory, which is in the<API-M_2.6.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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
- Download the identity component migration resources and unzip it to a local directory.
Re-index the artifacts in the registry.
Run the reg-index.sql script against the
REG_DB
database.Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.
Add the
tenantloader-1.0.jar
to<API-M_2.6.0_HOME>/repository/components/dropins
directory.Rename the
<lastAccessTimeLocation>
element in the<API-M_2.6.0_HOME>
/repository/conf/registry.xml
file.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
If the
<API-M_2.6.0_HOME>/
solr
directory exists, take a backup and thereafter delete it.- Start the WSO2 API-M server.
Stop the WSO2 API-M server and remove the
tenantloader-1.0.jar
from the<API-M_2.6.0_HOME>/repository/components/dropins
directory.
Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.2.0 configurations to 2.6.0
This step is only required if you have WSO2 API-M-Analytics configured in your current deployment.
As you are upgrading from WSO2 API-M Analytics 2.2.0, in order migrate the configurations required to run WSO2 API-M Analytics for WSO2 API-M 2.6.0 carryout the same instructions as mentioned in
Step 4 - Restart the WSO2 API-M 2.6.0 server
sh wso2server.sh
wso2server.bat
Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.1.0 to 2.6.0.
If you are using WSO2 Identity Server (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 WSO2 API-M 2.1.0 configurations
Do not copy entire configuration files from the current version of WSO2 API Manager to the new one, as some configuration files (e.g., api-manager.xml
) may have changed. Instead, redo the configuration changes in the new configuration files.
Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.
Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.
The Synapse configs of the super tenant are in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory.The 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.
- Download API Manager 2.6.0 from https://wso2.com/api-management/.
Open the
<API-M_2.6.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 WSO2 API Manager instance that is already being used.- User Store
- Registry database/s
- API Manager databases
Statistics database (If statistics are configured)
Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the
defaultAutoCommit
property is set totrue
by default for the following datasource configurations in themaster-datasources.xml
file.- WSO2_CARBON_DB
- WSO2AM_DB
- WSO2AM_STATS_DB
When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.
Edit the registry configurations in the
<API-M_2.6.0_HOME>/repository/conf/registry.xml
file and the user database in the<API-M_2.6.0_HOME>/repository/conf/user-mgt.xml
file, similar to the configurations of the current API Manager.Move all your Synapse configurations with the exception of the files mentioned below, by copying the contents in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory and by using it to replace the contents of the<API-M_2.6.0_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.6.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, you need to merge the changes to the corresponding files in 2.6.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
Move all your tenant Synapse configurations by copying the contents in the
<CURRENT_API-M_HOME>/repository/tenants
directory and adding the copied contents to the<API-M_2.6.0_HOME>/repository/tenants
directory.NOTE: Copy the files listed below from the
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default/sequences
directory and replace the corresponding files in the<API-M_2.6.0_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.
- 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.6.0_HOME>/repository/components/dropins
directory. - 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.6.0_HOME>/repository/components/lib
directory.
Step 2 - Upgrade WSO2 API-M 2.1.0 to 2.6.0
- Stop all WSO2 API Manager server instances that are running.
Make sure you backed up all the databases and Synapse configs, as instructed in step 1 of the previous section.
To start the migration process, run the respective migration script based on your environment.
Run the
apim210_to_apim260_gateway_artifact_migrator.sh
script, as shown below, to migrate from WSO2 API Manager 2.1.0 to 2.6.0../apim210_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.1.0 deployment, reside.The API definition paths
<API-definition-path>
are as follows:Super Tenant -
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
Tenant -
<API-M_2.6.0_HOME>/repository/tenants
Where,
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0
.Run the PowerShell script
apim210_to_apim260_gateway_artifact_migrator.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowerShell (PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim210_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.1.0 deployment, reside.Super Tenant -
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
Run the PowerShell script
apim210_to_apim260_gateway_artifact_migrator_for_tenants.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowerShell (PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim210_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.1.0 deployment, reside.Tenants -
<API-M_2.6.0_HOME>/repository/tenants
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
It may take a considerable amount of time, which is proportionate to the amount of artifacts, to complete the migration process.
Troubleshooting
Why do I get the following error - apim210_to_apim260_gateway_artifact_migrator.ps1 / apim210_to_apim260_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?
When running the
apim210_to_apim260_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 as the Administrator.Set-ExecutionPolicy RemoteSigned
Upgrade the WSO2 API Manager database from version 2.1.0 to version 2.6.0.
Download the
apimgt-db-migration-scripts-2.1to2.6.zip
and extract it.Execute the relevant database script, from the scripts that are provided in the extracted directory, on the
WSO2AM_DB
database.
If your MB Store database on WSO2 API-M 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 the MB store database in API-Manager.
Download
mb-store-migration-scripts-3.1.0_to_3.2.0.zip
and extract it.Execute the relevant database script, from the scripts that are provided in the extracted directory, on the
WSO2_MB_STORE_DB
database.
Upgrade the Identity component in WSO2 API Manager from version 5.3.0 to 5.7.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).
- Download the identity component migration resources and unzip it to a local directory.
Navigate to the latest release tag and download thewso2is-migration-x.x.x.zip
under Assets. - Copy the
migration-resources
folder from the extracted folder to the<API-M_2.6.0_HOME>
directory. Open the
migration-config.yaml
file in themigration-resources
directory and edit thecurrentVersion
element to 5.3.0, as shown below.migrationEnable: "true" currentVersion: "5.3.0" migrateVersion: "5.7.0"
Make sure you have enabled migration by setting the
migrationEnable
element totrue
.Remove the following entry from the
migration-config.yaml
file.- name: "EventPublisherMigrator" order: 11
Copy the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
from the extracted folder to the<API-M_2.6.0_HOME>
/repository/components/dropins
directory.Copy the keystores (i.e.,
client-truststore.jks
,wso2cabon.jks
and any other custom JKS) used in the previous version and replace the existing keystores in the<API-M_2.6.0_HOME>/repository/resources/security
directoryStart WSO2 API Manager 2.6.0 via the terminal 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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.
Troubleshooting
When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.
Sample exception stack traceERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} - Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; lastwait:60000
1. Change the value in <indexingFrequencyInSeconds> in
<APIM_HOME>/repository/conf/registry.xml
to a higher value (e.g., 10)2. Re-run the command above.
Make sure to revert the change done in Step 1, after the migration is complete
After you have successfully completed the migration, stop the server and remove the following files and folders.
Remove the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
file, which is in the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Remove the
migration-resources
folder, which is in the<API-M_2.6.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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
- Download the identity component migration resources and unzip it to a local directory.
Download WSO2 API Manager Migration Client, extract and copy org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar to
<API-M_HOME>/repository/components/dropins
directory.Start the WSO2 API-M server as follows.
sh wso2server.sh -DmigrateAccessControl=true
Re-index the artifacts in the registry.
Shut down WSO2 API Manager 2.6.0 (if you have already started it).
Run the
reg-index.sql
script against theREG_DB
database.Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.
Add the
tenantloader-1.0.jar
to<API-M_2.6.0_HOME>/repository/components/dropins
directoryRename the
<lastAccessTimeLocation>
element in the<API-M_2.6.0_HOME>
/repository/conf/registry.xml
file.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
If the
<API-M_2.6.0_HOME>/
solr
directory exists, take a backup and thereafter delete it.- Start the WSO2 API-M server.
- Stop the WSO2 API-M server and remove the
tenantloader-1.0.jar
from the<API-M_2.6.0_HOME>/repository/components/dropins
directory.
Make sure to remove the WSO2 API-M client migration jar (org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar) from the<API-M_2.6.0_HOME>/repository/components/dropins
directory as well.
Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.1.0 configurations to 2.6.0
This step is only required if you have API-M-Analytics configured in your current deployment.
As you are upgrading from WSO2 API-M Analytics 2.1.0, in order migrate the configurations required to run WSO2 API-M Analytics for WSO2 API-M 2.6.0 carryout the same instructions as mentioned in
Step 4 - Restart the WSO2 API-M 2.6.0 server
sh wso2server.sh
wso2server.bat
Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.0.0 to 2.6.0.
If you are using WSO2 Identity Server (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 WSO2 API-M 2.0.0 configurations
Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (e.g., 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.
Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.
The Synapse configs of the super tenant are in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory.The 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.
- Download API Manager 2.6.0 from https://wso2.com/api-management/.
Open the
<API-M_2.6.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 WSO2 API Manager instance that is already being used.- User Store
- Registry database/s
- API Manager databases
Statistics database (if statistics are configured)
Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the
defaultAutoCommit
property is set totrue
by default for the following datasource configurations in themaster-datasources.xml
file.- WSO2_CARBON_DB
- WSO2AM_DB
- WSO2AM_STATS_DB
When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.
Edit the registry configurations in the
<API-M_2.6.0_HOME>/repository/conf/registry.xml
file and the user database in the<API-M_2.6.0_HOME>/repository/conf/user-mgt.xml
file similar to the configurations of the current WSO2 API Manager.Move all your Synapse configurations, except the files mentioned below, by copying the contents of the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory and by using it to replace the contents of the<API-M_2.6.0_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 WSO2 API Manager 2.6.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, you need to merge the changes to the corresponding files in WSO2 API-M 2.6.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
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.6.0_HOME>/repository/tenants
directory.NOTE: Get the files listed below from the
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default/sequences
directory and replace the corresponding files in the<API-M_2.6.0_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, follow this step for the Gateway node.
- If you manually added any custom OSGI bundles to the
<API-M_2.0.0_HOME>/repository/components/dropins
directory, copy those to the<API-M_2.6.0_HOME>/repository/components/dropins
directory. - If you manually added any JAR files to the
<API-M_2.0.0_HOME>/repository/components/lib
directory, copy those and paste them in the<API-M_2.6.0_HOME>/repository/components/lib
directory.
Step 2 - Upgrade WSO2 API-M 2.0.0 to 2.6.0
- Stop all WSO2 API Manager server instances that are running.
Make sure you backed up all the databases and Synapse configs as instructed in step 1 of the previous section.
To start the migration process, run the respective migration script based on your environment.
Run the
apim200_to_apim260_gateway_artifact_migrator.sh
script, as shown below, to migrate from API Manager 2.0.0 to 2.6.0../apim200_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.0.0 deployment, reside.The API definition paths
<API-definition-path>
are as follows:Super Tenant -
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
Tenant -
<API-M_2.6.0_HOME>/repository/tenants
Where,
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0
.Run the PowerShell script
apim200_to_apim260_gateway_artifact_migrator.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowerShell (PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim200_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which are copied from the WSO2 API-M 2.0.0 deployment, reside.Super Tenant -
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
Run the PowerShell script
apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowerShell ( PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.Tenants -
<API-M_2.6.0_HOME>/repository/tenants
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
It may take a considerable amount of time, which is proportionate to the amount of artifacts, to complete the migration process.
Troubleshooting
Why do I get the following error - apim200_to_apim260_gateway_artifact_migrator.ps1 / apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?
When running the
apim200_to_apim260_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 as the Administrator.Set-ExecutionPolicy RemoteSigned
Upgrade the WSO2 API Manager database from version 2.0.0 to version 2.6.0.
Download the apimgt-db-migration-scripts-2.0to2.6.zip ZIP and extract it.
- Execute the relevant database script, from the scripts that are provided in the extracted directory, on the
WSO2AM_DB
database.
Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.7.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).
- Download the identity component migration resources and unzip it to a local directory.
Navigate to the latest release tag and download thewso2is-migration-x.x.x.zip
under Assets. Copy the
migration-resources
folder in the extracted folder to the<API-M_2.6.0_HOME>
.Open the
migration-config.yaml
file in themigration-resources
directory and edit thecurrentVersion
element to 5.2.0, as shown below.migrationEnable: "true" currentVersion: "5.2.0" migrateVersion: "5.7.0"
Make sure you have enabled migration by setting the
migrationEnable
element totrue
as defined above.Remove the following entries from the
migration-config.yaml
file, which is in themigration-resources
directory.- name: "EventPublisherMigrator" order: 11
and
- name: "ChallengeQuestionDataMigrator" order: 6 parameters: schema: "identity"
Copy the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
from the extracted folder to the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Copy the keystores (i.e.,
client-truststore.jks
,wso2cabon.jks
and any other custom JKS) used in the previous version and replace the existing keystores in the<API-M_2.6.0_HOME>/repository/resources/security
directory.Start WSO2 API Manager 2.6.0 via the terminal 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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.
Troubleshooting
When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.
Sample exception stack traceERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} - Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; lastwait:60000
1. Change the value in <indexingFrequencyInSeconds> in
<API-M_HOME>/repository/conf/registry.xml
to a higher value (e.g.,10)2. Re-run the command above.
Make sure to revert the change done in Step 1 , after the migration is complete
After you have successfully completed the migration, stop the server and remove the following files and folders.
Remove the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
file, which is in the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Remove the
migration-resources
directory, which is in the<API-M_2.6.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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
- Download the identity component migration resources and unzip it to a local directory.
Stop the WSO2 API-M server if you have started it. Download the WSO2 API Manager Migration Client, extract and copy org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar to the
<API-M_HOME>/repository/components/dropins
directory.Migrate Access Control support for API Publisher.
You have to run the following migration client to migrate the Access Control support for the API Publisher, because Publisher Access Control is enabled by default in WSO2 API Manager 2.6.0.sh wso2server.sh -DmigrateAccessControl=true
Stop the WSO2 API-M server and carryout migration for fault sequence from API-M 2.0.0 to API-M 2.6.0 using the migration client.
sh wso2server.sh -DmigrateFromVersion=2.0.0
Preserve the case sensitive behavior for the migrated resources by adding the following property to the
<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>
Re-index the artifacts in the registry.
Shut down WSO2 API Manager 2.6.0 (if you have already started it).
Run the
reg-index.sql
script against theREG_DB
database.Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.
Add the
tenantloader-1.0.jar
to<API-M_2.6.0_HOME>/repository/components/dropins
directoryRename the
<lastAccessTimeLocation>
element in the<API-M_2.6.0_HOME>
/repository/conf/registry.xml
file.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
If the
<API-M_2.6.0_HOME>/
solr
directory exists, take a backup and thereafter delete it.- Start the WSO2 API-M server.
Stop the WSO2 API-M server and remove the
tenantloader-1.0.jar
from the<API-M_2.6.0_HOME>/repository/components/dropins
directory. Make sure to remove the WSO2 API-M client migration jar (org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar) from the<API-M_2.6.0_HOME>/repository/components/dropins
directory as well.
Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.0.0 configurations to 2.6.0
This step is only required if you have WSO2 API-M Analytics configured in your current deployment.
As you are upgrading from WSO2 API-M Analytics 2.0.0, in order migrate the configurations required to run WSO2 API-M Analytics for WSO2 API-M 2.6.0 carryout the same instructions as mentioned in Upgrading from 2.5.0 to 2.6.0 - Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics.
Step 4 - Restart the WSO2 API-M 2.6.0 server
sh wso2server.sh
wso2server.bat
Follow the instructions below to upgrade your WSO2 API Manager server from APIM 1.10.0 to 2.6.0.
If you are using WSO2 Identity Server (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 WSO2 API-M 1.10.0 configurations
Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (e.g., api-manager.xml
) may have changed. Instead, redo the configuration changes in the new configuration files.
Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.
Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.
The Synapse configs of the super tenant are in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory.The 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.
- Download API Manager 2.6.0 from http://wso2.com/api-management/.
Open the
<API-M_2.6.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 WSO2 API Manager instance that is already being used.- User Store
- Registry database/s
- API Manager databases
Statistics database (if statistics are configured)
Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the
defaultAutoCommit
property is set totrue
by default for the following datasource configurations in themaster-datasources.xml
file.- WSO2_CARBON_DB
- WSO2AM_DB
- WSO2AM_STATS_DB
When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.
Edit the registry configurations in the
<API-M_2.6.0_HOME>/repository/conf/registry.xml
file and the user database in the<API-M_2.6.0_HOME>/repository/conf/user-mgt.xml
file similar to the configurations of the current WSO2 API Manager.Move all your Synapse configurations, except the files mentioned below, by copying the contents in the
<CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default
directory and by using it to replace the contents in the<API-M_2.6.0_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 WSO2 API-M 2.6.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, you need to merge the changes to the corresponding files in 2.6.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
Move all your tenant Synapse configurations.
Copy the contents in the<CURRENT_API-M_HOME>/repository/tenants
directory. Replace the contents in the<API-M_2.6.0_HOME>/repository/tenants
directory with the copied contents.NOTE: Get the files listed below from the
<API_M_2.6.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default/sequences
directory and replace the corresponding files in the<API_M_2.6.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.
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. Therefore, you may face issues when trying to migrate with an empty documentation summary field from an older version.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.6.0_HOME>/repository/components/dropins
directory.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.6.0_HOME>/repository/components/lib
directory.
Step 2 - Upgrade WSO2 API-M 1.10.0 to 2.6.0
- Stop all WSO2 API Manager server instances that are running.
Make sure you backed up all the databases and Synapse configs as instructed in step 1 of the previous section.
Before you run the migration client, open the
<API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml
file, and set the<username>
, and<password>
elements of theAM_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.
Example<datasource> ... <definition type="RDBMS"> <configuration> ... <username>xxxxxx</username> <password>xxxxxx</password> ... </configuration> </definition> </datasource>
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).
- Download the identity component migration resources and unzip it to a local directory.
Navigate to the latest release tag and download thewso2is-migration-x.x.x.zip
under Assets. - Find the correct DB script in the
wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/identity
directory. 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 directory Applicable DB Description wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/identity
AM_DB
Run the script against AM_DB. wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/um
UM_DB REG_DB
This script includes insert operations against the UM_CLAIM
table and some index creation scripts against REG_DB, which are required in order for you to upgrade from your previous WSO2 API-M version to WSO2 API-M 2.0.0. Please run the index creation queries against the REG_DB and UM_CLAIM table insert queries against the UM_DBFor example, if you are working with a MySQL DB, run the
mysql.sql
script.
- Download the identity component migration resources and unzip it to a local directory.
Download and extract the WSO2 API Manager migration client and do the following to upgrade your version of WSO2 API Manager to WSO2 API-M 2.0.0:
This migration client upgrades the WSO2 API Manager components from WSO2 API-M 1.10.0 to WSO2 API-M 2.0.0 first. Thereafter, from step 6 onwards, you need to carryout the rest of the changes that are required to upgrade from version WSO2 API-M 2.0.0 to WSO2 API-M 2.6.0.
- Copy the
org.wso2.carbon.apimgt.migrate.client-2.0.X.jar
file to the<API-M_2.6.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. - Copy the
migration-script
folder into<API-M_2.6.0_HOME>
.
If you use a clustered/distributed API Manager setup, copy themigration-script
folder to a Publisher node.Start API Manager 2.6.0 with the following command-line options to migrate the database, registry, and the file system, separately, in the given order.
Description Command To migrate the database only.
This migrates theAM_DB
database. Please ensure that the<API_M_PUBLISHER>/repository/conf/datasources/master-datasources.xml
file has an entry forAM_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.You may notice the "
Fault sequence migration from APIM 2.0.0 to 2.1.0 has started
" log message in this step which is used for fault sequence migration. This migration is also done in this step.-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 WSO2 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_2.6.0_HOME>/executionplans
directory. Therefore, you must run this command against a node that has Synapse config files and theAM_DB
. After the migration, copy the<API-M_2.6.0_HOME>/executionplans
directory to the<API-M_2.6.0_HOME>/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.Run 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 encounter the following error, 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 WSO2 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, because you are yet to complete the migration process.
You may notice the following exception being thrown in the console when WSO2 API Manager 2.6.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 WSO2 API Manager database. The instructions given from step 8 onwards address the creation of theIDP_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.6.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 exceptions when WSO2 API Manager 2.6.0 is started at this point.
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.IDN_CLAIM_DIALECT' doesn't exist
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.IDN_OIDC_SCOPE' doesn't exist
These errors will be resolved after following the instructions given under step 8 below.
- Copy the
Run the respective migration script, based on your environment.
Run the
apim200_to_apim260_gateway_artifact_migrator.sh
script, as shown below, to migrate from WSO2 API Manager 2.0.0 to 2.6.0../apim200_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were 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.6.0_HOME>/repository/deployment/server/synapse-configs/default
Tenant -
<API-M_2.6.0_HOME>/repository/tenants
Where,
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0
.Run the PowerShell script
apim200_to_apim260_gateway_artifact_migrator.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell appears, and the shell changes to PowerShell (PS).
Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
.\apim200_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.Super Tenant -
<API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
Run the PowerShell script
apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1
as follows:Open a Windows command prompt and type the following command.
powershell
A message about PowerShell (PS) appears, and the shell changes to PS.
Run the PowerShell script by passing the location of the Gateway artifacts that you need to migrate.
.\apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>
<API-definition-path>
- This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.Tenants -
<API-M_2.6.0_HOME>/repository/tenants
Where
<API-M_2.6.0_HOME>
can be, for example,/Users/user12/Documents/wso2am-2.6.0.
It may take a considerable amount of time, which is proportionate to the number of artifacts, to complete the migration process.
Troubleshooting
Why do I get the following error - apim200_to_apim260_gateway_artifact_migrator.ps1 / apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?
When running the
apim200_to_apim260_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
Upgrade the WSO2 API Manager database from version 2.0.0 to version 2.6.0.
Download the apimgt-db-migration-scripts-2.0to2.6.zip and extract it.
- Execute the relevant database script, from the scripts that are provided in the extracted directory, on the
WSO2AM_DB
database.
Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.7.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).
- Download the identity component migration resources and unzip it to a local directory.
Navigate to the latest release tag and download thewso2is-migration-x.x.x.zip
under Assets. - Copy the
migration-resources
folder in the extracted folder to<API-M_2.6.0_HOME>
. Open the
migration-config.yaml
file in the migration-resources directory and edit thecurrentVersion
element to 5.2.0, as shown below.migrationEnable: "true" currentVersion: "5.2.0" migrateVersion: "5.7.0"
Make sure you have enabled migration by setting the
migrationEnable
element totrue
as defined above.Remove the following entries from the
migration-config.yaml
file.- name: "EventPublisherMigrator" order: 11
and
- name: "ChallengeQuestionDataMigrator" order: 6 parameters: schema: "identity"
Copy the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
from the extracted folder to the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Copy the keystores (i.e.,
client-truststore.jks
,wso2cabon.jks
and any other custom JKS) used in the previous version and replace the existing keystores in the<API-M_2.6.0_HOME>/repository/resources/security
directoryStart API Manager 2.6.0 via the terminal 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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.
Troubleshooting
When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.
Sample exception stack traceERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} - Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; lastwait:60000
1. Change the value in <indexingFrequencyInSeconds> in
<API-M_HOME>/repository/conf/registry.xml
to a higher value (e.g., 10)2. Re-run the command above.
Make sure to revert the change done in Step 1 , after the migration is complete
After you have successfully completed the migration, stop the server and remove the following files and folders.
Remove the JAR (
org.wso2.carbon.is.migration-x.x.x.jar)
file, which is in the<API-M_2.6.0_HOME>/repository/components/dropins
directory.Remove the
migration-resources
directory, which is in the<API-M_2.6.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 thewso2server.bat
file.-Dmigrate -Dcomponent=identity
- Download the identity component migration resources and unzip it to a local directory.
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.6.0.
Download WSO2 API Manager Migration Client, extract and copy org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar (You can use the same JAR that downloaded in step 5 ) to the
<API-M_HOME>/repository/components/dropins
directory.Start the WSO2 API-M server as follows:
sh wso2server.sh -DmigrateAccessControl=true
Preserve the case sensitive behavior for the migrated resources by adding the following property to the
<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>
Re-index the artifacts in the registry.
Shut down WSO2 API Manager 2.6.0 (if you have already started it).
Run the
reg-index.sql
script against theREG_DB
database.Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.
Add the
tenantloader-1.0.jar
to<API-M_2.6.0_HOME>/repository/components/dropins
directoryRename the
<lastAccessTimeLocation>
element in the<API-M_2.6.0_HOME>
/repository/conf/registry.xml
file.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
If the
<API-M_2.6.0_HOME>/
solr
directory exists, take a backup and thereafter delete it.- Start the WSO2 API-M server.
- Stop the WSO2 API-M server and remove the
tenantloader-1.0.jar
from the<API-M_2.6.0_HOME>/repository/components/dropins
directory. Make sure to remove the WSO2 API-M client migration jar (org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar) from the<API-M_2.6.0_HOME>/repository/components/dropins
directory as well.
Step 3 - Optionally, migrate the statistics related data from WSO2 DAS to API Manager Analytics 2.6.0
This step is only required if you have WSO2 Data Analytics Server (WSO2 DAS) configured in your current deployment for analytics.
From WSO2 API Manager 2.0.0 onwards, statistics can be configured only for RDBMS, because the WSO2 API Manager 1.10.0 REST based analytics configurations no longer exists. Follow the instructions below to migrate statistics data from a previous versions of API Manager to WSO2 API-M 2.6.0.
If you have configured analytics using RDBMS -
- Take a backup of the API Manager statistics DB (
STAT_DB
). - Execute the relevant DB script found in
migration-scripts/110-200-migration/stat/
on theSTAT_DB
database that you configured in WSO2 DAS for WSO2 API-M 1.10.0.
After executing the DB script, now, yourSTAT_DB
is similar to theSTAT_DB
in WSO2 API-M 2.0.0. Directly migrate to WSO2 API-M 2.6.0 as mention in Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics, under the Upgrade from 2.5.0 to 2.6.0 tab.
You may notice that the following exceptions are thrown in the console when migrating at this point. These exceptions occur because the following tables were introduced only after WSO2 API-M 2.0.0. Therefore, you can safely ignore these exceptions.
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'TestStatsDB_new.API_REQ_USER_BROW_SUMMARY' doesn't exist.
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'TestStatsDB_new.API_EXE_TME_SUMMARY' doesn't exist
com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'TestStatsDB_new.API_REQ_GEO_LOC_SUMMARY' doesn't exist
If you configured analytics using the REST client in API-M 1.10.0 with DAS 3.0.x -
- Configure analytics using WSO2 API Manager 1.10.0 and WSO2 DAS 3.0.x with the RDBMS client based on the instructions in Publishing API Runtime Statistics Using RDBMS, which is in the WSO2 API-M 1.10.0 documentation.
- Wait for data to appear on the RDBMS and WSO2 API Manager statistics dashboard.
Take a backup of the WSO2 API Manager statistics DB (
STAT_DB
).- Execute the relevant DB script found in
migration-scripts/110-200-migration/stat/
on theSTAT_DB
that you configured in WSO2 Data Analytics (WSO2 DAS) for WSO2 API Manager 1.10.0.
After executing the DB script, now, yourSTAT_DB
is similar to theSTAT_DB
in WSO2 API-M 2.0.0. - Directly migrate to WSO2 API-M 2.6.0 as mention in Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics, under the Upgrade from 2.5.0 to 2.6.0 tab.
Step 4 - Restart the WSO2 API-M 2.6.0 server
sh wso2server.sh
wso2server.bat
Follow the instructions below to upgrade your WSO2 API Manager server from APIM 1.8.0/1.9.0/1.9.1 to 2.6.0.
If you are using WSO2 Identity Server (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-M 1.8.0/1.9.0/1.9.1 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.6.0.
Upgrade your current WSO2 API-M version (1.8.0/1.9.0/1.9.1) to WSO2 API-M 2.0.0 as explained in the WSO2 API-M 2.0.0 documentation.
Step 2 - Upgrade WSO2 API-M 2.0.0 to API-M 2.6.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.6.0. For more information, see Upgrading from 2.0.0 to 2.6.0.
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. Therefore, there is no need to migrate them manually.
Tip 2: From 2.6.0 onwards, WSO2 API Manager is configured by default to trigger token clean up during token generation, token refreshing and token revocation. For more details, see Configuring API Manager for token cleanup. Therefore, when the state of the token ( TOKEN_STATE)
is changed during any of the latter mentioned processes for tokens that were ACTIVE before the migration process and/or for tokens that will be generated after the migration process, by default, such tokens will be removed from the IDN_OAUTH2_ACCESS_TOKEN
table and stored in an audit table. However, the old tokens which were already inactive, revoked or expired before the migration will not be cleaned by the same token cleanup process. Therefore, alternatively, after the migration, you could follow step 3 in the Using stored procedures for token cleanup section and use the given token clean up script to manually clean up the old inactive, revoked, and expired tokens from the IDN_OAUTH2_ACCESS_TOKEN
table.
Tip 3: 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. In addition, you need to remove any existing .svn
directories in the new deployment's <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default
directory and the <API-M_2.6.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default
directory before starting the servers. For more details, see Configuring Deployment Synchronization.