WSO2 has introduced a new way of updating, called Updates 2.0, which is different from the method we had until now. But why should you update anyway?
Software, some people say, is never finished. No, I am not talking about project management woes. I am talking about the fact that software like WSO2, adapts to new functionality and, equally important, often uses components developed by others. This means that there are many ‘moving parts’ that continuously need updates to add, fix or update pieces of code.
In other words, updates are necessary, and you need to plan for them. It might not be known beforehand when an update is available, but it is important that you have a process in place to manage the deployment of them.
To update or not to update WSO2 products
You might say, that is a no brainer. You just said that updates are necessary. And you are right, I did say that. However, WSO2 updates are only available to paying customers. The subscription fees are a source of revenue for WSO2 and allows them to develop their products so we can use them.
WSO2 updates include improvements that are released by WSO2, on top of a released WSO2 product version. With updates, you do not have to wait until the next product version release to get the product enhancements and security fixes. As far as I am concerned it is a must-have if you are running WSO2 in your business. This is not a sneaky way to promote the Product Support that we offer, no, I am dead serious.
We deploy software and systems not as a hobby, but in order to conduct business. Business that relies on the systems and a disturbance can be quite costly. Also, in this day and age, organizations are under a magnifying glass. Media is quite happy to report about organizations that show vulnerabilities to all kinds of threats. When this concerns personal data, from a GDPR perspective there is a requirement to notify a supervisory authority within 72 hours. All in all, these are things that you would probably like to avoid.
WUM vs Update 2.0
Until now we had WUM (WSO2 Update Manager), a command line tool that allowed us to create a repository and apply available updates to the baseline version creating a new version of the product with a timestamp suffix. It is important to realize that WUM works with an out of the box version of WSO2 in which NONE of your changes, parameters and settings have been applied. So, each updated version needs to be configured to reflect your settings and subsequently tested.
What is not widely known, in recent versions of WSO2 products you can find commands to do an in-place update. These tools like update_linux which can be found in the bin directory (e.g., in the WUM version of WSO2 API Manager 3.2.0) applies the updates to that specific version.
WSO2 Updates 2.0 works from the directory where it is installed. A special command, e.g., wso2update_linux will make sure that for customers with valid Product Support the updates are downloaded and applied. The mechanism is quite similar to WUM (download patches and apply) as we can see when we run the update with -v (verbose) as an additional parameter.
Updates and hotfixes
Updates can consist of, for instance, security fixes, new features or improvements or bug fixes on an existing product. When an update is applied, the update level is incremented. In our example the WSO2 API Manager level is 26.
As you can see from the image, the fictional company Acme updates the WSO2 product but also gets hotfixes for issues that occur and are fixed. A hotfix is a zip file that is added locally. ‘Other Corp’ gets the hotfixes as regular updates.
Working with Updates 2.0
As you can see there are three separate versions for the three operating systems WSO2 will run on:
- Windows: wso2update_windows.exe
- Linux: wso2update_linux
- Mac: wso2update_darwin
These are not scripts, like for instance to start WSO2 (wso2server.sh), but executables.
When you want to update a WSO2 product, the first step is to update the tool itself. This screen shows the flow on Windows. Linux and Mac are roughly the same as far as the steps and functionality go. For instance, the possibility to revert an update does not exist on windows. So, it does matter what platform you are using, I am showing Windows below. In general, we would suggest running on a Linux environment.
What functions does the tool have?
If we want to know what we can do with the tool the parameter help will show the options. Commands and flags can be combined as you can see from the examples in the screenshot.
It is important to realize that we have Commands and Flags, as you can see from the screenshot above. Some of these flags have a shortcut like for instance ‘-p’ for- ‘–password’.
The aforementioned –revert is not a command, it is a flag. There is a revert-hotfix command but that is specifically for updates that are supplied as hotfixes, in other words a zip file that you need to locally add to your WSO2 product.
Contrary to WUM we do not have an update command, the update is done when we start the tool. We are also able to provide user and password information to the tool as additional parameters. This allows to automate the process; however, it requires plain text username and password to be stored. A quick check with regards to the password shows that it sometimes needs to be entered with a single quote, like this: -p ‘myPa55!word’. In Linux, characters like ! are used by bash for special purposes. In that case, put single quotes around the password as this indicates that this part should not be interpreted.
Dry run allows you to test the procedure. A dry run executes all the steps to update the distribution but makes no persistent changes. It allows us to test whether the update procedure is expected to finish successfully.
Current state shows the level, in this case 25.
apply-hotfix allows you to add a hotfix to the product. remove-hotfix (not shown) will remove it again.
What is the status
Online you can see the Update Summary for this product. The URL is https://updates-info.wso2.com. You can drill down by clicking on the turquoise button (136 UPDATES) and see the individual updates.
Resolve conflicts
There can be situations where there is a conflict between the current version and the incoming update. This could be a configuration file, or an artifact that you have customized. If a file or an artifact has conflicts, the update tool does not attempt to merge them. In such a situation, you need to manually apply the customizations on top of the updated files.
Especially when you have automated the update-process then a conflict occurrence can become a problem. In such cases you could consider running the update-process on a non-customized product distribution and use tools like Ansible, Chef, Puppet etcetera to apply your customizations after the updates have been applied by the WSO2 Updates tool.
You can minimize conflicts by following best practices. One of them is not to modify the Jar, War or Car files shipped with the product. An update will overwrite these files and your changes are lost. War files (Web Application Resource file) will be updated by unarchiving it and applying updates on top according to WSO2. Chances are that any War customizations could be retained after the update but be sure to check it!
Car files supplied by you will not be changed by the update process so no worries about them. For.jag/js and json files it is important to stick to the original indentation. Also keep the order of parameters in json files as much as possible, adding new key value pairs at the end.
When you do have an issue, these are the three simple steps. Where we say *.original, the * signifies one or more files.
- Find the files that are in conflict and are reported by the tool;
- Find the *.original file (what is in your current setup) and the *.new (what is in your update);
- Resolve the issues and save it as *.final. Run the update with –continue and check the outcome. All conflict files should be gone (original, new, and final).
Working with Docker
One of the features I find cool is the possibility to create a docker image out of the updated product we just created. The image is stored in docker locally and you can use it as your new product base image.
As you can see, we added an updated version to the docker repo.
Continuous updating of WSO2 products
This blog gives an overview of the WSO2 Updates 2.0 tool. This information can be used to set up a process of continuous updating, however that does require a lot more. With this I mean, scripting (ansible), testing, deploying and automation of everything.
The WSO2 Updates 2.0 tool allows users to update an existing configuration. The previous WUM tool allowed to update only the product versions provided by WSO2. However, as we saw, there was possibility to do an in-place update with the update command (e.g., update_windows.exe). There are pros and cons to both approaches.
Applying updates to the WSO2-provided installation, so having none of your own customizations, will eliminate the chances of any update-conflicts on an existing installation. You can solve any update-issues early in the process and before actually applying them in a live environment. Such approach does mean though that automating the installation and configuration of your environment is highly advised as on each update you need to re-deploy the WSO2 product in the environment.
With the WSO2 Updates 2.0 approach such re-deployment is no longer required. You can now choose to apply the updates on a live environment, or you apply them on the WSO2-provided non-customized installation and rollout the update through an automated provisioning process.
In both cases though doing a test-cycle of the update is always recommended. Test that the update is applied as you expect and that nothing breaks.
If you need to manage your WSO2 installation yourself then we recommend automating the installation and configuration of your WSO2 products as that will increase the reproducibility of your installation and ease the efforts needed to apply updates and perform the rollout on your environment.
When all of the above seems to be a bit too complicated for your liking then do come and have a look at our Connext product where we host, install and configure the WSO2 products for you. That way, you can focus on doing your primary business and let us handle the API Management, Integration and Identity & Access Management with WSO2 for you!
