Upgrading Guidelines

This section contains the complete upgrading process related to the WSO2 API Manager. Go through the guidelines given below before attempting to upgrade the production environment.

If you are migrating API-M from a version older than 2.6.0
If you are migrating IS as KM from a version older than 5.7.0


If you require a zero downtime migration, you must contact WSO2 support. We do not recommend proceeding with zero downtime migration without WSO2 support. You can contact WSO2 Support for assistance.


For more information about this release, see About this Release.

  1. If you already have a WSO2 subscription, reach out to our support team through your support account.

  2. Always migrate to the latest version as the latest fixes and new features are available in the latest version. If you already have a WSO2 subscription, you can use the Update Management Tool(UMT) to get any fixes or latest updates for this release. If you have a particular requirement to migrate to an intermediate version, contact WSO2 Support.


    Migrating the production environment requires additional hardware/VM resources because both the old environment and the new environment will be running until all the traffic is routed to the new environment.

  3. Make sure to take backups of the existing databases used by the current WSO2 API Manager Server. This backup is necessary in case the migration causes any issues in the existing database.


    Check on the Tested DBMS for API-M 4.1.0. Only those versions will be supported in migration as well. Therefore, if you are currently on an older database version, please migrate your database to the supported version first before proceeding with the migration

  4. If you have customizations in your setup, check if they are supported out-of-the-box in the latest version.

    • If your customizations are already available in the latest version, you can remove the customization after migration. You can contact WSO2 Support for assistance.
    • If any custom requirement is not available in the latest version, migrate the customization to support the latest product version. Note the following points.

    Migrating the customizations that are not available in the latest version

    • Initially, update the dependency version of the dependant WSO2 components and re-build the customized component.
    • As a practice, WSO2 does not make API changes in minor releases of the dependency JARs. However, if there are API changes, please update the custom code and re-build.
  5. List down the functional and non-functional use cases in your deployment and create test cases for them.


    This step is crucial to verify that the migrated environment works as expected.

  6. Identify the configuration migrations required for the new setup.

    For more information on the new config model introduced, see the Configuration Catalog.

  7. Prepare a test setup of the upgrading version with customizations and necessary config changes, and test your functional and non-functional requirements.

  8. Before start the upgrading process, Please make sure that you have read the whole documentation specific to the version upgrade and have a clear understanding of the upgrading process.

  9. If you have expired certificates in client-trustore, follow Renewing a CA-Signed Certificate in a Keystore

  10. If you have many APIs, there could be a high load on the database during the migration. Hence, increase the database pool size during migration. Please refer Tuning JDBC Pool Configurations for more details.

  11. Start the migration from the lowest environment (e.g., dev) and continue up to the highest before the production (e.g., pre-prod). Run the test cases in the migrated environments to confirm that your functional and non-functional requirements are met in the migrated environment.

  12. Before you carry out the production migration, run a pilot migration on your pre-prod environment.

    It will be ideal if the pre-prod environment is similar to the production environment.

    • If possible, restore a database dump of the production environment to the pre-prod environment and perform the pilot migration.

    • If the production database dump cannot be used, at least ensure that you have a sufficient amount of data in the database to mimic the production environment.

  13. When you follow the above instructions, you can get a rough estimate of the time for the final production update, and you can allocate time slots based on the above analysis.

    WSO2 recommends that you perform the migration while the system is under minimum traffic.

  14. When attempting to migrate a distributed setup, you need to do the data migration for the Control Plane profile only. You can do the migration using the following command:

    sh api-manager.sh -Dprofile=control-plane -Dmigrate -DmigrateFromVersion=<product-version-number> -DmigratedVersion=4.1.0 -DrunPreMigration
  15. Disable versioning in the registry configuration when migrating IS as a Key Manager from versions older than IS 5.9.0.

    If there are frequently updating registry properties, having the versioning enabled for registry resources in the registry can lead to unnecessary growth in the registry related tables in the database. To avoid this, versioning has been disabled by default in API Manager 4.1.0.

    Therefore, if registry versioning was enabled in older versions of WSO2 API-M, it is required to run registry version disabling scripts against the database that is used by the registry. For example, see step 5 under Migrating the API Manager configurations for the associated scripts.

  16. If you are using PostgreSQL, during the migration, "uuid-ossp" extension is created in the database. In order to create this extension, the database user should have the 'Superuser' permission. If the user is not already a superuser, assign the permission before starting the migration.

  17. When migrating a Kubernetes environment to a newer API Manager version, it is recommended to do the data migration in a separate VM, a local machine, or a single container. Once the data migration is complete, you can simply move the migrated databases into the containerized deployment in Kubernetes.

    To implement this kind of scenario you have to follow the first four steps in the migration documentation (for example the first four steps when migrating API-M 3.2.0 to API-M 4.1.0 in a separate VM/container/local machine and then move the databases to a containerized setup before doing step 5, which is to re-index the API-M artifacts. Make sure to use a new mount for the solr and remove the older solr mount from the deployment.

After you have completed the above instructions and are satisfied with the outcome, proceed with the production migration process. After the migration is complete, verify the migration process using the following instructions.

  • Monitor the system health (CPU, memory usage, etc.).
  • Monitor the WSO2 logs for errors.