is
2022/04/11
11 Apr, 2022

Migrate from WSO2 Open Source to WSO2 Subscription

  • Lashan Sivaganeshan
  • Senior Software Engineer - WSO2

Introduction

WSO2 provides open-source products licensed under the Apache 2.0 license. Today, thousands of the world’s largest corporations, leading universities, and governments rely on our open-source, cloud-native, uniquely extensible products and industry solutions. Together with WSO2’s product stack, we execute in excess of 18 trillion transactions, expose more than 200,000 APIs, and manage over 100 million identities every single year. WSO2’s product stack consists of three standalone products: WSO2 API Manager, WSO2 Enterprise Integrator, and WSO2 Identity Server, which can be deployed in both cloud and on-premises environments.

With regard to the above products, WSO2 does not have any community/enterprise version split. However, we provide support services, maintenance, consulting, training, and a range of other essential services around the free software with an annual subscription to develop a strong value proposition and earn customer loyalty. Additionally, major enterprise projects should always be covered by enterprise-grade support.

The difference between open source and subscribed versions of WSO2 products

In terms of major features, the open source and subscription versions are identical. However, there are clear key differentiators between the versions.

  • Subscribed versions include all bug and security fixes reported by subscribers, whereas the open-source version will receive these updates in the next release.
  • The subscribed versions receive real-time WSO2 updates (fixes) to the installation itself, whereas the open-source version does not.
  • WSO2 expert support is available 24x7x365 for subscribed versions (unlimited production/incident support and query support proportionate to the subscription paid), whereas community support is only available through Slack, GitHub, and StackOverflow for open-source versions.




Another significant benefit of a WSO2 subscription is that you will receive technical support and guidance from a Technical Owner who will assist you with solution design when your team requires it.

Moreover, with the subscription, you are eligible to get WSO2 paid services for architectural reviews, quick start programs, workshops, product training, and deployment implementations.

This article explains how to migrate from the open source version to the subscription version as well as how to acquire a subscription. This will allow the open source version users to receive the subscription's benefits, including updates.

What are updates and updating the subscription setup?

As previously stated, the product's subscription version includes all bug and security fixes necessary for production-grade enterprise deployment. WSO2 updates are simple to obtain. Your deployment environment will be updated with the most recent bug fixes and software improvements with only one simple command. Updates-2.0 (U2 in short) is a framework that makes the updating process easier. WSO2 subscribers can also use the "Updates Information Portal" at any time to see the most recent information. More information on the update procedure and U2 can be found at the following link.



This is how getting constant updates on the product pack looks.

Simply run the wso2update os> script from the product-home>/bin folder to acquire an update. The following document contains detailed information on how to obtain updates.

The distribution will be reconditioned with the latest artifacts, including the OSGi bundles in the product pack's plugins directory, once the update is completed. The update tool includes logs to help you figure out which JARs and other files were updated.

The first step in migrating your open-source WSO2 distribution to a subscription-based distribution with updates is to obtain a pack containing the U2 updates. To put it another way, you're getting a U2 updated pack. To obtain this, go to the wso2.com website and download the binary distribution (.zip archive) for the product and version you're running, then run the wso2update <os> script as indicated in the above instructions. This updated pack (U2 updated pack) will be utilized in the migration procedure as outlined in the following steps once the U2 update is completed.

Note: If you're using a containerized deployment, upgrading to the subscription version is as simple as acquiring the image from our private repository with U2 updates applied. Updates for U2 are handled by making new images that are labeled with the version number.

You can compare the differences between the prior open-source version and the U2 updated version after you have the U2 updated pack. The directory structure will remain the same, and the altered files will be visible as seen below. The updated files will also be logged in the product-home/updates/logs directory.

Prerequisites before migration

  • Validate the size of your deployment with a WSO2 Solution Architect (who will also serve as your Technical Owner) and obtain a subscription for the WSO2 products you utilize. With the help of WSO2 specialists, this would be a great opportunity to conduct capacity planning operations.
  • Using the credentials you received following your subscription, download the U2 updated binary pack (as described above).
  • Identify all of the adjustments and changes you've made to the WSO2 community version.
  • When you migrate the product to the subscription version, make sure you have a mechanism to test the existing behavior.
  • If you plan to execute a DB migration to a secondary database identical to the community version you use, get a DB dump or backup and use it to duplicate the databases for the migrated product version.

Note: In theory, no database schema modifications will be made in the subscription version compared to the community version. However, if there are any, they will be noted in the WSO2 update summary that you will receive during the U2 update.

Migrating the Binary Distribution to the Subscription Version

WSO2 API Manager migration

Naming convention 

 Open Source WSO2 API Manager Server -> OS_WSO2APIM

 Subscription based (U2 Updated) WSO2 API Manager Server -> SUB_WSO2APIM

To migrate your open source WSO2 API Manager product to the U2 updated WSO2 API Manager of the same version, follow the steps below.

  • Copy the configurations from deployment.toml file in <OS_WSO2IS> and add them in the deployment.toml file in <SUB_WSO2IS>/repository/conf.
  • If any configuration changes have been done in the <OS_WSO2IS>/bin directory, then merge the changes in the relevant files in <SUB_WSO2IS>/bin.
  • Get the diff of jar files in the <OS_WSO2IS>/repository/components/dropins and <SUB_WSO2IS>/repository/components/dropins and copy the additional files from OS_WSO2IS to SUB_WSO2IS, /repository/components/dropins folder.
  • Get the diff of jar files in the <OS_WSO2IS>/repository/components/libs and <SUB_WSO2IS>/repository/components/libs and copy the additional files from OS_WSO2IS to SUB_WSO2IS, /repository/components/libs folder.
  • If you have done any changes to the webapps in <OS_WSO2IS>/repository/deployment/server/webapps such as authenticationendpoint and accountrecoveryendpoint, copy those changed web apps to <SUB_WSO2IS>/repository/deployment/server/webapps folder.
  • Copy the keystores from <OS_WSO2IS>/repository/resources/security to <SUB_WSO2IS>/repository/resources/security folder.
  • If you have any tenants, copy all the folders in <OS_WSO2IS>/repository/tenants/ folder and paste them inside <SUB_WSO2IS>/repository/tenants/ folder.
  • If you have any secondary userstores in <OS_WSO2IS>/repository/deployment/server/userstores/, copy them and paste them to <SUB_WSO2IS>/repository/deployment/server/userstores/ folder.

WSO2 Identity Server migration

Naming convention 

 Open Source WSO2 Identity Server -> OS_WSO2IS

 Subscription based (U2 Updated) WSO2 Identity Server -> SUB_WSO2IS

Follow the below steps to migrate your open source WSO2 Identity Server product to U2 updated WSO2 Identity Server of the same version

  • Copy the configurations from deployment.toml file in <OS_WSO2IS> and add them in the deployment.toml file in <SUB_WSO2IS>/repository/conf.
  • If any configuration changes have been done in the <OS_WSO2IS>/bin directory, then merge the changes in the relevant files in <SUB_WSO2IS>/bin.
  • Get the diff of jar files in the <OS_WSO2IS>/repository/components/dropins and <SUB_WSO2IS>/repository/components/dropins and copy the additional files from OS_WSO2IS to SUB_WSO2IS, /repository/components/dropins folder.
  • Get the diff of jar files in the <OS_WSO2IS>/repository/components/libs and <SUB_WSO2IS>/repository/components/libs and copy the additional files from OS_WSO2IS to SUB_WSO2IS, /repository/components/libs folder.
  • If you have done any changes to the webapps in <OS_WSO2IS>/repository/deployment/server/webapps such as authenticationendpoint and accountrecoveryendpoint, copy those changed web apps to <SUB_WSO2IS>/repository/deployment/server/webapps folder.
  • Copy the keystores from <OS_WSO2IS>/repository/resources/security  to <SUB_WSO2IS>/repository/resources/security  folder.
  • If you have any tenants, copy all the folders in <OS_WSO2IS>/repository/tenants/ folder and paste them inside  <SUB_WSO2IS>/repository/tenants/ folder.
  • If you have any secondary userstores in <OS_WSO2IS>/repository/deployment/server/userstores/, copy them and paste them to <SUB_WSO2IS>/repository/deployment/server/userstores/ folder.



Migrating Customizations to the Subscribed Versions

There are mainly three types of customizations that can be done to WSO2 products as follows:

  • Custom extensions 
  • These are custom implementations created by implementing existing WSO2 product interfaces or extending existing WSO2 product source code classes. This category can include standard extension points like custom handlers and connectors. Because this is the typical approach to customizing WSO2 products, it will have no direct impact on existing product behavior. Because it has no effect on the ordinary U2 process, you can copy these extensions from drop-ins or lib folders to the subscribed version's drop-ins and lib folders.

    Furthermore, you should discuss these customizations with the Technical Owner to ensure that they follow best practices and should be included in the deployment.

  • Customizations on source code in GitHub
  • The subscription process may be complicated if any customizations are included in the open source version by updating and compiling the source code.

    These kinds of customizations aren't advised for the subscription version, but if you've done them in the open source version you've been using, please contact WSO2 support or your Technical Owner. The experts at WSO2 will walk you through the process.

  • Patches included in the patches directory
  • If you have any patches included in the <product-home>/repository/components/patches directory by building certain source repositories with customizations, please note that even if you take U2 updates, all the fixes will be overridden by the jar files in the patches folder. This is not a recommended practice in the latest WSO2 products and as mentioned above, all patches are provided through U2. Therefore in this case also recommend getting an official U2 update for the product from WSO2 for the relevant patch you use. The Technical Owner will assist in this process as well. 

    Migrating the docker distribution to a subscription 

    WSO2 allows you to choose the deployment style based on your preferences, and we also supply Docker images for building containerized deployments. Most containerized systems use container-native solutions like the WSO2 Micro-Integrator, WSO2 Streaming-Integrator, and Choreo-Connect.

    You can upgrade to the U2 updated subscription version if you have community version container images of any WSO2 product and an active subscription. To do so, run the following command using the subscription credentials to pull the appropriate images from the WSO2 private Docker registry based on the tag.

    docker login docker.wso2.com

    docker pull docker.wso2.com/wso2is:XXXX

    All Docker images in the WSO2 private Docker registry adhere to a special image tagging format reflecting the update levels. You can read more on Docker versioning tags from the following link

    Post-migration tasks

  • After finishing all steps above, you can start the reconditioned U2 updated pack which contains artifacts related to your previous open-sourced setup.
  • Once a U2 updated pack is implemented with the above steps, the deployments can be configured by replicating the created U2 updated pack in the relevant deployments. 
  • Before trying the U2 updated pack in production, test all scenarios while including performance and UI tests. 
  • Using a configuration management tool such as Ansible will make the process of getting continuous updates for your Dev, Staging, and Production environments easier.
  • It’s possible to conduct the above migration with zero downtime as well. If there’s such a requirement, you can follow a process such as Blue-Green or Canary in the lower environments and proceed with a production cut-over. 
  • Once the setup is migrated successfully, do the needful to keep the setup updated by running the U2 tool frequently in order to make sure the deployment contains all recent updates.


  • Conclusion

    By acquiring a WSO2 subscription, you can take a giant step forward in your digital transformation journey by receiving regular upgrades to your deployment. The process of transitioning from the open-source to the subscription version entails a number of steps, and the WSO2 team will guide you through them all to ensure a smooth transition.



     

    About Author

    • Lashan Sivaganeshan
    • Senior Software Engineer
    • WSO2

    Lashan is an Associate Lead - Solutions Engineer at WSO2. Prior to joining WSO2, Lashan worked at Millennium Information Technologies as a quality assurance analyst where he was responsible for building and maintaining large scale capital market software. He holds a bachelor’s degree in computer science.