Simple Understanding of WSO2 APIM Migration Process
This blog will help to get some clear understanding of the migration steps of WSO2 APIM. For a complete migration, the below steps need to be completed.
- Migrate the configuration related to the previous version
- Migrate the API related resources
- Migrate the custom implemented extensions
- Migrate the databases
- Re-index the registry after the migration (and before starting the new version)
Here I will guide about how those steps completed when following the official documentation.
Migrate the configuration related to the previous version
In this section, we need to identify the configuration changes we have done for the default APIM pack(GA released pack). The configuration changes in the below files can be identified as the main configuration changes for the migration.
- <APIM_HOME>/repository/conf/datasources/master-datasources.xml
- <APIM_HOME>/repository/conf/registry.xml
- <APIM_HOME>/repository/conf/user-mgt.xml
Migrate the API related resources
When we publish an API in WSO2 APIM, the resources related to the particular API will be deployed in the <APIM_HOME>/repository/deployment/server/synapse-configs/default directory.
The main resources can be identified as synapse resource of the API(<APIM_HOME>/repository/deployment/server/synapse-configs/default/api), synapse resources of endpoint(<APIM_HOME>/repository/deployment/server/synapse-configs/default/endpoints), synapse resource of mediation extensions used in the particular API(<APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences).
The main intention of migrating synapse resources of the API is to transform into the newer version-specific handlers.
For the tenants, the above locations should be changed as <APIM_HOME>/repository/tenants directory.
But we need to make sure that, not to export(replace) the default resources which are mentioned in the WSO2 official documentation to the newer version. Because those may contain some improvements related to the product versions. If we have added any custom changes for those files in the previous version, we have to merge those to the default resources available in the newer version.
This action can be performed by the provided script of ‘apim_xxx_to_apim_xxx_gateway_artifact_migrator.sh.
Migrate the custom implemented extensions
If we have implemented any custom extensions such as handlers, the extension of the default handlers or any manually added JAR files and OSGI bundles for the previous version, we have to manually add them to the newer versions as well. Also, we need to upgrade the dependencies of the custom handlers and extensions as well.
So we need to,
add the custom OSGi bundles to the <APIM_HOME>/repository/components/dropins directory, and
add any JAR files to the <APIM_HOME>/repository/components/lib directory.
Migrate the databases
There are several improvements and newly added features in the version upgrade of the APIM. To reflect those, the databases will also have newly added tables and columns. So it will be better to keep in mind that during the migration process, some of those tables and columns will not be filled by processing the older data.
The database migration process is performed as two main steps such as Identity-related component’s data migration and APIM related component’s data migration. These database migrations will be performed by the provided migration clients in the official documentation.
Re-index the registry after the migration (and before starting the new version)
Once after the successful database migration(running of the provided migration clients), we need to re-index the registry of the newer version. The WSO2 APIM uses Apache Solr based indexing. The newly added data may not be indexed as the same as the previous version of the APIM server. So we need to perform a registry re-indexing.
Hope you find this blog post helpful to get a basic understanding of product migration without just following the steps. Cheers!!
References
[1] https://docs.wso2.com/display/AM260/Upgrading+from+the+Previous+Release
