Flex Gateway新着情報
Governance新着情報
Monitoring API ManagerMule 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. |
Mule runtimes use semantic versioning, therefore please note that Mule applications:
|
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:
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. |
For every application that you update:
Import the application to Anypoint Studio as a Mule project.
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.
Make any other changes to your Mule project that may be necessary depending on the version gap you’re transitioning.
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.
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. |
Download the new Mule version from the Customer Portal and install it (preferably on a different server or virtual machine).
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 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. |
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.
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.
Run your new Mule Server to verify your installation is working as expected.
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.
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.
Deploy your applications to your new Mule Server.
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 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:
Go through steps 1 through to 5 of the previous section, Mule Standalone Runtime Version
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
Copy the mule-agent-plugin folder from the path <MULE_HOME>/plugins
from your old Mule installation into the same on the new installation.
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 |
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:
Follow the steps in Application Runtime Version to update your application.
Find the application on the Applications tab on Runtime Manager and click Choose File to upload the new Mule Deployable Archive (.zip file).
Follow these steps to upgrade the Mule version in a Runtime Manager server group:
Go to Anypoint Runtime Manager.
Switch to the corresponding environment.
Select Servers in the navigation menu.
Select the server group to update.
In the server group dashboard, select the Servers tab and select the server to upgrade.
In the actions dropdown menu, select Shutdown.
Repeat the previous two steps for each server in your server group.
Open a terminal in the local machine that hosts your Mule instance.
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
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
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
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
)
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
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
Start Mule:
cd ${MULE-3.9.5_HOME}/bin
./mule start
Go to Runtime Manager to confirm that your Mule applications are deployed and displayed as Running.
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.
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:
Disband any existing cluster (if any).
Unregister all your servers from the old MMC version.
Undeploy the previous MMC version from your servlet container/application
server.
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:
Stop your application server (E.g: Tomcat).
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).
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).
Replace the configuration files on this new MMC version with the files that you backed up from the older version in the previous step.
Pack/Compress the folder contents back, and make sure its extension is .war
(simply rename the file’s extension, if necessary).
Start you application server and undeploy the previously installed MMC version.
Restart your application server and deploy the new version of MMC.
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:
<MMC_HOME>/WEB-INF/web.xml
<MMC_HOME>/WEB-INF/classes/META-INF/mmc-ldap.properties
<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 |
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.
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:
Install the new Mule Runtime in all of the servers.
Configure these new Mule instances as members of a different cluster.
Node by node, do the following:
Remove the old Mule instance from the load balancer so it won’t receive new invocations.
Shut down the old Mule instance.
Start up the new Mule instance.
Deploy all the applications to this new Mule instance.
Register the new Mule instance to the load balancer.