Upgrading the Mule Runtime in a Standalone instance can be challenging. Fortunately, Mulesoft provides us with a Mule Upgrade Tool that can greatly help us in this process.In this post, we will create a Lab, where we will upgrade a Mule server standalone from an old version of the runtime to a newer version and use the Mule Upgrade Tool. The purpose of this lab will be to learn how to use the Mule Upgrade Tool and plan an upgrade of our Mule runtime.
What is the Mule Upgrade Tool
The Mule Upgrade Tool helps us automate much of the upgrade process. The tool is very useful to identify configuration differences between the old and the new version and incompatibilities with connectors, libraries or other components. This helps us reduce the risk of missing essential configurations or dependencies and, therefore, reduces the chance of post-upgrade issues.The Mule Upgrade Tool also provides us with a roll back mechanism, allowing us to get back to the previous version very easily (and quickly) in case the upgrade does not go well.
Lab Setup
As mentioned above, in this lab we will take a server with an old version of the Mule runtime and we will use the Mule Upgrade Tool to upgrade it to the currently latest version of the Mule Runtime.Let’s see the initial setup. To start off, we need a VM where we will install a standalone instance of the mule runtime. In this tutorial, we will use an Ubuntu Server 24.04 LTS running on an AWS EC2 instance.
Mule Server Installation
Here’s a summary of the steps required for the installation. We will be following our previous post How to install the Mule Runtime on Ubuntu Server, click on that post if you want to see the installation process in detail.- Install Java JDK - In this tutorial we’ll use OpenJDK 17
- Set up the JAVA_HOME environment variable
- Download and install an old mule runtime version
- Create a folder for Mule - In this tutorial we use the folder /home/ubuntu/mule
- In this tutorial we’ve downloaded mule runtime 4.6.8
- Unzip the mule runtime zip file in the Mule folder
- Set up the MULE_HOME environment variable pointing to the installation folder. In our case that will be /home/ubuntu/mule/mule-enterprise-standalone-4.6.8
- Set up the PATH environement variable to include the Java and Mule installation paths
- Install the Mule runtime as a Linux Service
sudo $MULE_HOME/bin/mule install
- Register the Mule runtime in the control plane and start the Mule
Deploy Applications to the Mule Server
For testing the upgrade, we’ll upload a couple of helloMule apps. For this tutorial, we’ll not use anything special, just an http listener with a logger and a set payload to say Hello Mule. To make it simple we’ll use two ports:- 8081 for mule-app-1
- 8082 for mule-app—2
Deploy them to our Mule Runtime 4.6.8
With that, we’re ready to upgrade our Mule Server.
Upgrade Process
In this tutorial, we’ll upgrade the Mule Runtime from version 4.6 to version 4.8. For that, we’ll go through the following steps:Prepare the server for the upgrade
- First, we need to download the target version of the mule runtime (4.8.0).
- Extract the zip file of the new mule runtime version. After you extract the file remove the zip file, we don’t need it anymore. In our example we’ll extract it to our Mule folder at ~/mule.
- Download the Mule Upgrade Tool from the Customer Portal and extract it into $MULE_HOME/tools. After you extract the file remove the zip file, we don’t need it anymore. In this tutorial, we’ll use the latest version available of the tool, 1.1.4. The content of the $MULE_HOME/tools should look like this.
- Stop the Mule Runtime. You can do that from Runtime Manager or from the server running the command
sudo systemctl stop mule_ee
Run the Mule Upgrade Tool
- Run the upgrade tool with the following command
$MULE_HOME/tools/upgrade-tool upgrade -n <newMuleDistributionAbsolutePath>
sudo $MULE_HOME/tools/upgrade-tool upgrade -n /home/ubuntu/mule/mule-enterprise-standalone-4.8.0/
- If you get the error
Then try to run the command from the tools folder:
cd $MULE_HOME/tools
sudo ./upgrade-tool upgrade -n /home/ubuntu/mule/mule-enterprise-standalone-4.8.0
- If there’s any mismatch between the files of the old and new mule runtimes (which usually happens), the tool will raise an error, telling you where the conflict is
- Normally these conflicts happen because we have modified the configuration of the old runtime. So, review the custom configurations you might have added in the files pointed out by the tool. In our example, we can see the upgrade tool is telling us that the wrapper.conf file has conflicts
- To get more details we can have a look at the logs of the upgrade tool located at $MULE_HOME/tools/mule-runtime-upgrade-tool-logs/mule-runtime-upgrade-tool-logs.log
cat $MULE_HOME/tools/mule-runtime-upgrade-tool-logs/mule-runtime-upgrade-tool-logs.log
Resolve the conflicts
The upgrade tool provides us with a useful way to deal with these mismatches between files of the old and new runtime versions.When there’s a conflict, the upgrade tool will create the following content under the
upgrade-tool folder of the old Mule runtime version:
- $MULE_HOME/upgrade-tool/mule-config/conflicts/ready - In this folder, the upgrade tool will save the files with no conflicts that will be used for the upgraded version of the runtime
- $MULE_HOME/upgrade-tool/mule-config/conflicts/to_review - In this folder, the upgrade tool will save the files of the old version where it has found conflicts
- $MULE_HOME/upgrade-tool/mule-config/conflicts/
new-${MULE_HOME_NEW_FOLDER_NAME}- In this folder, the upgrade tool will save the files of the new version where it has found conflicts
new-${MULE_HOME_NEW_FOLDER_NAME} and to_review folders and solve the conflicts. And we need to do that for each file with conflicts. This is probably the most tedious part of the upgrade process. The good news is that the upgrade tool helps us to identify these files with conflicts. If not, doing it manually, it’s very easy to miss one small difference between versions.To solve the file conflicts, we can use a diff tool to compare both files.
In this tutorial, we’ve found conflicts with the wrapper.conf file as you can see in the below screenshot:
For example, we can use the Diff feature of Visual Studio Code:
After reviewing the differences, modify one of the two files to produce a final version of the file and then copy it to the
ready folder. That will inform the upgrade tool what’s the final version of that file.Re-run the Mule Upgrade Tool
Next, re-run the upgrade command again. Now, if there are no more conflicts, the upgrade tool should proceed with the upgrade.cd $MULE_HOME/tools
sudo ./upgrade-tool upgrade -n /home/ubuntu/mule/mule-enterprise-standalone-4.8.0
If everything went well we will see the successful message at the end. Notice that the upgrade tool will also check the version of the Mule Agent to be upgraded. In our example there’s no need, as it is running the latest version of the Mule Agent.
Optionally, we can run the status subcommand of the upgrade tool to get information about the upgrade process we’ve just run:
Optionally, we can run the status subcommand of the upgrade tool to get information about the upgrade process we’ve just run:
cd $MULE_HOME/tools
sudo ./upgrade-tool status
Lastly, we will delete the folder with the newer version, as we no longer need it. The upgraded Mule runtime instance has replaced the previous version because the target location was $MULE_HOME, which corresponds to the previous version.
For that reason, in this case, there’s no need to change the $MULE_HOME env variable.
For that reason, in this case, there’s no need to change the $MULE_HOME env variable.
Start the Mule
With that the upgrade process is finished and we and we can start the mule runtime:sudo systemctl start mule_ee
How to Roll back the upgrade
Things can go wrong. If that’s the case, the upgrade tool provides us with a roll back mechanism. The Mule Upgrade Tool, before starting the upgrade tool, generates a backup of the Mule instance. This backup can be used in case we need to rollback along with the rollback subcommand.
For that, with the mule runtime stopped, type the following:
$MULE_HOME/tools/upgrade-tool rollback
After that, start the mule runtime and verify that you’ve successfully rolled back to the previous version
Summary
In summary, the Mule Upgrade Tool is efficient, reduces the risk of human error, and automates compatibility checks.The only caveat of using the Mule Upgrade Tool is that it requires the mule runtime to be stopped during the migration process, which might be an issue in environments that require zero downtime.