1. Homepage
  2. Release Notes

  3. Upgrading Mule Runtime Engine(Versions 3.x to 3.n)

Upgrading Mule Runtime Engine(Versions 3.x to 3.n)

Mule 3.x Upgrades Only (For guidance with migrations from Mule 3.x to Mule 4, see Mule 4 for Mule 3 Users.)

This document describes considerations and best practices when changing the 3.x versions of Mule runtime engine on your on-premises servers in the following deployments:

  • Mule standalone instances

  • Mule instances on-premises through Runtime Manager

Keep in mind that if you’re deploying your applications to CloudHub, then this content is not relevant to you, with the exception of the steps outlined in the section Application Runtime Version. Changing the Mule runtime version of a Mule application that’s deployed to on CloudHub is simply managed from the runtime version drop-down box in the application settings deployment configuration page.

Application Runtime Version

Mule runtimes use semantic versioning, therefore please note that Mule applications:

  • Are most likely not compatible between major runtime versions releases (e.g. z.0.0)

  • Are potentially compatible between minor runtime version releases (e.g: 3.y.0), but MuleSoft recommends executing a regression test cycle to validate this.

  • Are assured to be fully compatible for patch releases of the Mule runtime (e.g: 3.8.x)

Before you begin, read the release notes for the Mule Runtime version you wish to upgrade to (which we will call the target version, from here on), to know if you must make any necessary changes to your applications to ensure compatibility. For example, if you migrate from a version that’s older than 3.6 to a version that’s newer, you might want to change all HTTP connectors to the newer version of this connector as the old one is deprecated as of Mule Runtime 3.6.

If there are no relevant changes between the Mule Runtime version in which the application is developed and the target Mule Runtime version to which you’re migrating, then you shouldn’t need to modify your application. Mule Runtimes support having applications that are built with older Mule versions deployed to them.

If you do decide to change your Mule application’s version, you must:

  1. Download the newest Mule runtime on Anypoint Studio so that you can handle that version in the IDE.

    You can check this documentation page, as a reference on how to install additional runtimes on Anypoint Studio.

  2. For every application that you update:

    1. Import the application to Anypoint Studio as a Mule project.

    2. Navigate the package explorer on the left to find its mule-project.xml file and open it. Change the Mule version by selecting it from the Server Runtime dropdown menu.

      updating mule versions 364d6

    3. Make any other changes to your Mule project that may be necessary depending on the version gap you’re transitioning.

    4. Export your project as a Mule Deployable Archive (.zip file).

If you use Maven to build your application, edit its pom.xml file to change the muleVersion property value, so that it matches the target version.

Once the Mule Deployable Archives (.zip files) are in versions that you’re sure are compatible with the target runtime version and you’ve also validated that any other necessary changes that ensure compatibility have been applied, you can move on to installing the corresponding Mule Runtime on your servers.

Mule Standalone Runtime Version

To ensure that you have faster downtime and an easier backup route, we recommend that you initially install your new Mule Runtime on a separate server from where you have your current Mule Runtime installed.

  1. Download the new Mule version from the Customer Portal and install it (preferably on a different server or virtual machine).

  2. If any of your applications use shared custom libraries, make sure you copy those .jar files to the <MULE_HOME>/lib/user directory of the new version.

    If any of your previous applications rely on a full or a partial custom patch in order to work properly (these would be found in the folder <MULE_HOME>/lib/user), please verify that the fix is included in this target release by reviewing the corresponding release notes page.

    Otherwise, please contact MuleSoft Support by creating a new support case, to request a new patch compatible with the target version. Patch files are version specific and MUST NOT be used in a different runtime version.

  3. Download a new copy of your license from the Customer Portal and install it on the target version, by following the instructions described at Installing an Entrerprise License.

  4. If you have set any custom configurations to your runtime instance – for example: if you defined a different maximum heap size in the wrapper.conf file – you might want to replicate these settings manually.

  5. Run your new Mule Server to verify your installation is working as expected.

  6. Depending on the circumstances and your current infrastructure, you might want to consider shutting down your previous Mule Server at this point. Please evaluate the impact of this action before proceeding.

  7. If you have previously set any environment variables, such as MULE_HOME or PATH, make sure that they are now pointing to the new Runtime’s installation path.

  8. Deploy your applications to your new Mule Server.

Mule Runtime Version on Runtime Manager

To migrate following these steps, you must have the Runtime Management Agent installed. The agent comes bundled with Mule runtime as of version 3.6.0 and later. In case you’re migrating from a Mule runtime version that is older than that, you must do this migration manually.
To ensure that you’ll have less downtime and an easier backup route, we recommend that you initially install your new Mule Runtime on a separate server from where you have your current Mule Runtime installed. That way you can set everything up and only then decouple the old server and initiate the new one.

To migrate your Mule servers on-premises that are being managed through Runtime Manager, you must perform these steps on each:

  1. Go through steps 1 through to 5 of the previous section, Mule Standalone Runtime Version

  2. Copy the following three files from the path <MULE_HOME>/conf from your old Mule installation into the same on the new installation:

    • mule-agent.yml

    • mule-agent.jks

    • truststore.jks and/or anypoint-truststore.jks

  3. Copy the mule-agent-plugin folder from the path <MULE_HOME>/plugins from your old Mule installation into the same on the new installation.

  4. Open a terminal window and navigate to the <MULE_HOME>/bin of your new Mule installation. Once there, run the following command:

    amc_setup -U

    Through executing this command, you’re installing the latest version of the Runtime Manager Agent on your Mule runtime, which is assured to be compatible with your target runtime version. The files you copied from your old installation hold all of the configuration information that registers the Mule instance on Runtime Manager, so no further steps should be needed.

    Even when you’re installing your new Mule runtime version on another server or VM, the copied configuration files should suffice to smoothly transition the Mule instance’s identity on the Runtime Manager.

    If your origin server had apps that were deployed to it through the Runtime Manager, there’s no need to manually copy these, as they automatically upload to your new server when instructed to deploy them through Runtime Manager.

    Applications must be running and showing as Started in Runtime Manager. This process does not migrate stopped Applications.

  5. At this point the Mule server is already updated to the target version. Updating the Mule applications that are deployed to it is optional. If wish to do so to take full advantage of the features of the target runtime, then you must also:

    1. Follow the steps in Application Runtime Version to update your application.

    2. Find the application on the Applications tab on Runtime Manager and click Choose File to upload the new Mule Deployable Archive (.zip file).

Upgrade the Mule Runtime Version in a Runtime Manager Server Group

Follow these steps to upgrade the Mule version in a Runtime Manager server group:

  1. Go to Anypoint Runtime Manager.

  2. Switch to the corresponding environment.

  3. Select Servers in the navigation menu.

  4. Select the server group to update.

    1. In the server group dashboard, select the Servers tab and select the server to upgrade.

    2. In the actions dropdown menu, select Shutdown.

    3. Repeat the previous two steps for each server in your server group.

  5. Open a terminal in the local machine that hosts your Mule instance.

  6. If your Runtime Manager agent version is earlier than 1.12.0, upgrade to the latest version.

    Go to the current Mule Home directory and run the following commands:

    cd ${MULE-3.8.4_HOME}/bin

    cp ~/Downloads/agent-setup-1.15.3.zip .

    unzip agent-setup-1.15.3.zip

    ./amc_setup -U

  7. Go to the target directory for the new Mule runtime version and install it:

    cd ${MULE-3.9.5_DIRECTORY}

    cp ~/Downloads/mule-ee-distribution-standalone-3.9.5.zip .

    unzip mule-ee-distribution-standalone-3.9.5.zip

  8. Install the latest agent version:

    cd mule-enterprise-standalone-3.9.5/bin

    cp ~/Downloads/agent-setup-1.15.3.zip .

    unzip agent-setup-1.15.3.zip

    ./amc_setup -I

    rm ../conf/mule-agent.yml

  9. Copy the following files from the previous Mule runtime /conf directory to the new Mule runtime /conf directory:

    • All YAML files (*.yml)

    • All keystore files (*.jks)

  10. Confirm that the DNS configured in mule-agent.yml has the following values:

    websocket.transport:
  consoleUri: wss://runtime-manager.anypoint.mulesoft.com:443/mule

authenticationProxy:
  endpoint: https://data-authenticator.anypoint.mulesoft.com

  11. If you installed domains in your previous Mule instance, copy those domains to your new Mule instance:

    cp -R ${MULE-3.8.4_HOME}/domains${MULE-3.9.5_HOME}/domains

  12. Start Mule:

    cd ${MULE-3.9.5_HOME}/bin

    ./mule start

  13. Go to Runtime Manager to confirm that your Mule applications are deployed and displayed as Running.

Upgrading a Runtime Manager Cluster

Copy the mule-cluster.properties file located in the $MULE_HOME/.mule/ directory from your old Mule installation in the same folder on the new installation to configure the Mule runtime instance to work as a cluster node.

Zero downtime cannot be guaranteed when migrating clusters to another version. At some point during the migration the cluster is in a mixed state, with coexisting nodes running two different versions. This might lead to incompatible communication protocols between Hazelcast instances.
When such errors occur, every node in the cluster must be shut down to proceed with the migration.

Mule Management Console Versions

Note that unless instructed otherwise, you need to upgrade your MMC version to handle the corresponding Mule Runtime. See our policies regarding MMC versioning. Keep in mind that Mule versions prior to 3.5 aren’t supported on MMC.

For each of the servers that you manage through MMC, go through steps 1 through to 5 of the section, Mule Standalone Runtime Version

If you use default persistence on MMC, the recommended way to migrate to a newer MMC version is to perform a clean install of MMC and then register your existing Mule Servers to this new version. In that case, before installing the new version you must:

  1. Disband any existing cluster (if any).

  2. Unregister all your servers from the old MMC version.

  3. Undeploy the previous MMC version from your servlet container/application server.

  4. Delete the mmc-data folder (after making a backup of it)

On the other hand, if you prefer to perform an upgrade directly, once you have the latest copy of the MMC .war file (available for download through our Support Center), you must then follow these steps:

  1. Stop your application server (E.g: Tomcat).

  2. In case you have enabled LDAP support and/or configured an External Database, you must backup all the custom configuration files ( see the Backing up MMC Configuration Files section below).

  3. Uncompress the recently downloaded MMC .war file (you can simply manually change the .war extension to .zip and it can then be handled by any software that supports the .zip extension).

  4. Replace the configuration files on this new MMC version with the files that you backed up from the older version in the previous step.

  5. Pack/Compress the folder contents back, and make sure its extension is .war (simply rename the file’s extension, if necessary).

  6. Start you application server and undeploy the previously installed MMC version.

  7. Restart your application server and deploy the new version of MMC.

Backing up MMC Configuration Files

The following information applies to MMC versions 3.4.2 and 3.5.x onwards to the latest.

The following files need to be backed up from your current MMC installation in order to preserve any custom configuration it may have, such as LDAP support and External Database configurations:

  1. <MMC_HOME>/WEB-INF/web.xml

  2. <MMC_HOME>/WEB-INF/classes/META-INF/mmc-ldap.properties

  3. <MMC_HOME>/WEB-INF/classes/META-INF/databases/<type_of_data>-<database name>.properties

The <MMC_HOME> path could either refer to the copy of your custom/"already configured" MMC .war file you are currenlty deploying, or to the current exploded MMC’s application folder at your application server application directory.

Please note that these are only configuration files, by backing them up you are NOT preserving the current state of your MMC.

Make sure that MMC and the application servers are not running at the moment you back these files up

MMC Agent Version

Also, for earlier MMC versions than 3.4.0, make sure the version of the Mule Agent you use is also compatible with your target Runtime version.

For MMC Agent versions, the rule of thumb is the following:

For Mule versions 3.4.0 and later:

  • The MMC Console (or Server) version should be greater or equal to the ESB version.

  • Since the MMC Agent comes bundled with the Mule Runtime, there is no need to download it separately. If the MMC version is later than the ESB version, the bundled agent works transparently and there is no need to download it separately.

For Mule versions earlier than 3.4.0:

  • The MMC Agent version should be the same as the Mule Runtime version.

  • The MMC Console (or Server) version should be greater or equal to the Runtime version.

Upgrading an MMC Cluster With Zero Downtime

These steps are valid only for clusters created with MMC.

To achieve a zero downtime upgrade you need to have an external load balancer and set up two different clusters (it is not possible to have a cluster with mixed Mule Runtime versions).

You need to implement the following procedure:

  1. Install the new Mule Runtime in all of the servers.

  2. Configure these new Mule instances as members of a different cluster.

  3. Node by node, do the following:

    1. Remove the old Mule instance from the load balancer so it won’t receive new invocations.

    2. Shut down the old Mule instance.

    3. Start up the new Mule instance.

    4. Deploy all the applications to this new Mule instance.

    5. Register the new Mule instance to the load balancer.

See Also

Please feel free to contact MuleSoft Support if you have any question that is not covered by this article.