How to Upgrade an On Premises Mule Runtime with Runtime Manager

There are different ways of upgrading the Mule Runtime on a Standalone instance. One of them is to use the Mule Agent and Runtime Manager to move from one Mule Runtime version to a newer one.

This is a process that can be done within the same server, that is, an in-place upgrade. But normally, in a production environment, we would install a new server in parallel, with the newer Mule Runtime version to minimize the downtime.

In this post, we will prepare a Lab and see how to upgrade a Mule Runtime running on a Server from one version to a newer one running on another server by using Runtime Manager.

Lab Setup

In this Lab, we will install two servers:

One server with Mule Runtime version 4.6 (this will run on my Laptop)
One server with Mule Runtime version 4.8 (this will run on an AWS EC2 instance)

We will first install a Mule server with an older Mule Runtime Version (4.6) and deploy a couple of Mule apps. This will allow us to see how apps are moved from one server to the other during the upgrade process.

Secondly, we will set up another server, where we’ll install a newer Mule Runtime Version (4.8) with everything we need for the upgrade.

Once both servers are ready, we will shut down the old instance and make a request to Runtime Manager to replace our first Mule Server with the second Mule server that runs on the newer runtime version. We’ll see how Runtime Manager will deploy our existing apps in our new server.

Let’s see it step by step:

Installation of First Mule Server

Here’s a summary of the steps required for the installation. We will be following our previous post on 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. You can download it from your Customer Portal

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 environment variable to include the Java and Mule installation paths

Install the Mule runtime as a Linux Service

sudo $MULE_HOME/bin/mule install

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

Installation of Second Mule Server

For the second server we’ll repeat the same steps:

Install Java JDK - Same version as first server, OpenJDK 17
Set up the JAVA_HOME environment variable
Download and install the newer mule runtime version. You can download it from your Customer Portal.

Create a folder for Mule - Same as the first server, at /home/ubuntu/mule
In this tutorial, we’ve downloaded Mule runtime 4.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.8.0.
Set up the PATH environment variable to include the Java and Mule installation paths.

Install the Mule runtime as a Linux Service

sudo $MULE_HOME/bin/mule install

DO NOT REGISTER THIS RUNTIME IN THE CONTROL PLANE!!!
Run the mule runtime to verify it works. You can do that by running

$MULE_HOME/bin/mule

or running the mule service you’ve just created

sudo systemctl start mule_ee

Replicate your customizations

This is a delicate part. We need to identify all the custom configurations we have applied to our current Mule Server. Pay special attention to the $MULE_HOME/conf folder, which contains a few configuration files and check if you’ve set up any customization in the past.

For example, you might have modified the wrapper.conf file to fine tune the CPU, Memory, the garbage collector and other JVM-specific parameters.
An alternative to find your customizations is to compare the configuration files of both runtimes - compare the same files in the current and in the new server. For that, you could use a diff tool. For instance, you could take the wrapper.conf file in both servers and use Visual Studio Code to compare both and spot the differences.

Once we’ve identified all customizations, we need to replicate them to the new server.
Lastly, don’t forget to run again the mule runtime in the new server, to make sure it can run with the customizations you’re applying from the old runtime

Copy the Mule Agent files

During this upgrade process, we are not registering a new server. What we’re doing is to replace the current server with the new one. And the way to do it is by moving the Mule Agent files from one server to the other one. For that, we need to:

Copy from the $MULE_HOME/conf folder in the current server to the same folder in the new server the following files:

mule-agent.yml
mule-agent.jks
truststore.jks and/or anypoint-truststore.jks

Copy the mule-agent-plugin folder from <MULE_HOME>/server-plugins from the current Mule server into the same folder on the new Mule server.

There are multiple ways to copy files from one server to the other. In my case, I like to use the scp utility. It’s quick and secure. In this tutorial, I’m using two AWS EC2 instances, so I need to use a certificate for that:

scp -i [YOUR_CERT] path/to/your/file USER@[HOSTNAME_TARGET_SERVER]:/path/to/new/server/file

In this example:

sudo scp -i my-cert.pem $MULE_HOME/conf/mule-agent.yml ubuntu@172.31.19.243:/home/ubuntu
sudo scp -i my-cert.pem $MULE_HOME/conf/mule-agent.jks ubuntu@172.31.19.243:/home/ubuntu
sudo scp -i my-cert.pem $MULE_HOME/conf/anypoint-truststore.jks ubuntu@172.31.19.243:/home/ubuntu

sudo scp -r -i my-cert.pem $MULE_HOME/server-plugins/mule-agent-plugin ubuntu@172.31.19.243:/home/ubuntu

Install the Mule Agent on the Second Server

Here’s where the magic happens. We haven’t registered the Mule Runtime on the second server to the Control Plane yet. Now it’s the time to do that. The files we’ve just copied hold all the configurations to register the new runtime and replace the previous one.

Before we install the Mule Agent make sure to STOP THE CURRENT MULE RUNTIME. Once the runtime is stopped, run the following command on the new server:

sudo $MULE_HOME/bin/amc_setup -U

If everything goes well you should get a successful message confirming the mule agent has been updated/installed

Start the Mule Runtime on the New Server

Time to see if the upgrade process worked. Start the Mule on the new server by running the command

sudo systemctl start mule_ee

Check the Mule Apps

What about our Mule Apps? do we have to redeploy them? No! The benefit of upgrading using this method is that Runtime Manager will automatically upload the apps in our previous instance to the new one. Have a look at the server in Runtime Manager and verify:

The version of our Server has been upgraded to the newer one (the process has not added a new server, it’s replaced the previous one with the one)
The apps have been deployed and are up & running

We can also verify, in the new server that the apps have been uploaded to the /apps folder

ls -al $MULE_HOME/apps

Lastly, verify that your applications work as expected

Rollback

What if anything goes wrong during the process? In that case, rolling back to the previous runtime version is easy. We have not changed anything in the original server so, all we have to do is:

Stop the Mule Runtime on the new server
Start the Mule Runtime on the old server

The agent configuration is the same for both so, you will see that we can get the old server back up and in Runtime Manager it will show the older runtime version and the apps up & running.