How to deploy to Runtime Fabric with the Mule Maven Plugin

byGonzalo Marcos -

The Mule Maven Plugin is a Maven plugin developed by MuleSoft that allows us to manage, package, and deploy Mule applications using the Maven build automation tool. It simplifies the process of automating tasks related to Mule projects, such as building, deploying, and testing applications, by integrating with the Mule Runtime, either locally or remotely.
With this plugin, we can automate the deployment of our Mule apps to the different Mule Target Deployments:
  • Mule Standalone
  • Cloudhub 1,.0
  • Cloudhub 2.0
  • Runtime Fabric

In this post, we will see how to use the Mule Maven Plugin to deploy our Mule apps to Runtime Fabric. 
If you’re looking to deploy your apps to a different Target Deployment check out the other posts of this Series:
Here are the steps to follow for Runtime Fabric:

Prerequisites

To follow this tutorial we will need the following:
  • An instance of Runtime Fabric - if you don’t have one, you can install one for testing very easily with K3s, following the steps in the post How to Install Mulesoft Runtime Fabric on K3s
  • Maven installed on the computer (or server) from which you will be deploying your Mule app. The minimum version required to follow this tutorial is Maven 3.9.0
  • The minimum version of the Mule Maven Plugin required to deploy to Runtime Fabric should be greater than 3.7. In this tutorial, we will use version 4.3.0 of the plugin

Create a Connected App

Technically speaking, the Mule Maven Plugin can use User Credentials or a Connected app to deploy applications. However, it’s always recommended to use a Connected App, for security reasons. So, the first thing we need is a Connected App for our Maven deployments. 
So, the first thing we have to do is to create a Connected App in our Anypoint platform.

For that, go to Anypoint > Access Management > Connected Apps and click on Create app


Then, provide a name for your Connected App and choose the App act on its behalf (client credentials) option. 


As a best practice, we want to follow the least-privileged principle and grant only the minimum permissions for our Connected App to deploy to Runtime Fabric. The Mule Maven plugin will be connecting to the Anypoint control plane to perform 2 operations:
  • Upload the jar artifact of our app to Exchange.
  • Using that jar, deploy the app in Runtime Manager

Click on Add Scopes and add the following ones:
  • Under General:
    • View Environment
    • View Organization
  • Under Design Center
    • Design Center Developer
  • Under Runtime Manager:
    • Read Applications
    • Create Applications
    • Delete Applications
    • Manage Application Data
    • Read Runtime Fabrics
  • Under Exchange:
    • Exchange Contributor

Select the Business Groups and the Environments on which you are planning to deploy with the Mule Maven plugin


Click on Save


You should now see our new Connected App in the list with its client id and secret that we will use in the next step.


Update the settings.xml file

As we mentioned above, before deploying the app in Runtime Manager, the Mule Maven Plugin will publish the packaged Mule app (the jar file) to Exchange. 
Exchange is the private Maven repository, in Maven terms. As such, we need to provide the credentials to that repository in the settings.xml file of the Maven installation.

Head over to your laptop or to the server from which you will run the Mule Maven Plugin and open the settings.xml file. It should be located at ~/.m2 (Linux) or C:\Users\[USER]\.m2. 
In Maven, credentials for a repository are added as a <server> element. We need to add the following:

<settings>
    …
    <servers>
        …
        <server>
            <id>anypoint-exchange-v3</id>
            <username>~~~Client~~~</username>
            <password>{CLIENT_ID}~?~{SECRET}</password>
        </server>
        …
    </servers>
    …
</settings>

Where:
  • ~~~Client~~~ tells Maven these are Connected App credentials
  • {CLIENT_ID} and {SECRET} are the client id and secret of our Connected app.


Create a new Mule Project

Let’s create a test mule app for this test. Go to Anypoint Studio and create a new Mule Project. Open the POM file and make the following changes:

Maven coordinates

To deploy to Runtime Fabric, we need to use the Anypoint Org Id or Business Group Id where we will be deploying our app
<groupId>[BUSINESS_GROUP_ID]</groupId>
<artifactId>[APP_NAME]</artifactId>
<version>1.0.0</version>
<packaging>mule-application</packaging>


Mule Maven Plugin in your project

Anypoint Studio, by default, adds the Mule Maven Plugin to our POM. Make sure you’ve got it within the plugins and build sections:

<build>
    <plugins>
        …
        <plugin>
        <groupId>org.mule.tools.maven</groupId>
            <artifactId>mule-maven-plugin</artifactId>
            <version>${mule.maven.plugin.version}</version>
            <extensions>true</extensions>
        </plugin>
        …
    </plugins>
    …
</build>

Update the version of the Mule Maven Plugin in the properties section. The mule maven plugin required to deploy to Runtime Fabric should be greater than 3.7. In this tutorial, we will use version 4.3.0 of the plugin

<project>
    …
    <properties>
        …
        <mule.maven.plugin.version>4.3.0</mule.maven.plugin.version>
        …
    </properties>
    …
</project>


distributionManagement element

The last thing we need to do to configure the Mule Maven Plugin to use the Connected App credentials is to add a distributionManagement in the POM file or the application we want to deploy. The goal of a distributionManagementelement in a POM file is to provide the location of the Private repository where our app will be deployed. In our case, this is our Private Exchange.

For that, we will add this element pointing to Exchange V3 at the end of the pom file:

<project>
    …
    <distributionManagement>
        <repository>
            <id>anypoint-exchange-v3</id>
            <name>Private Exchange Repository</name>
            <url>https://maven.anypoint.mulesoft.com/api/v3/organizations/${project.groupId}/maven</url>
            <layout>default</layout>
        </repository>
    </distributionManagement>
</project>

Make sure the id of the repository matches the id of the server element we defined in the settings.xml file. Maven uses this id to search for the credentials of this repository.
Notice that, in the URL tag of the repository we are using the Business Group Id where the app will be published. It’s referenced by the project.groupId property of the POM, which is the BG Id we provided in the Maven coordinates.


The configuration of the Mule Maven Plugin for Runtime Fabric contains many parameters. In order to understand better how to use the plugin we will do two types of configurations:
  • Basic - With only the minimum and required parameters to deploy our app to Runtime Fabric
  • Advanced - Where we will explore the optional parameters of the plugin to fine tune our deployment to Runtime Fabric


Configure the Mule Maven Plugin (Basic)

For a basic configuration, we’d add this configuration to the Mule Maven Plugin within the build section of the POM file:

<project>
    ...
    <build>
        ...
        <plugin>
            <groupId>org.mule.tools.maven</groupId>
            <artifactId>mule-maven-plugin</artifactId>
            <version>${mule.maven.plugin.version}</version>
            <extensions>true</extensions>
            <configuration>
                <runtimeFabricDeployment>
                    <uri>https://anypoint.mulesoft.com</uri>
                    <provider>MC</provider>
                    <businessGroupId>${project.groupId}</businessGroupId>
                    <environment>Sandbox</environment>
                    <target>RTF-GON</target>
                    <muleVersion>${app.runtime}</muleVersion>
                    <server>anypoint-exchange-v3</server>
                    <applicationName>${project.name}</applicationName>                  
                    <replicas>1</replicas>
                </runtimeFabricDeployment>
            </configuration>
        </plugin>
        ...
     </build>
     ...
</project>

Where:
  • <runtimeFabricDeployment> Tells the plugin to deploy to RTF
  • <uri> - This is the URL of the Control plane. It’s not required. If not set, by default it is https://anypoint.mulesoft.com. If you are using the EU control plane you will have to set it to https://eu.anypoint.mulesoft.com
  • <provider> - Set to MC for RTF
  • <businessGroupId> - The BG Id where you are deploying to. You can take it from the maven coordinates of the project referencing it with ${project.groupId}. This is only required if you’re deploying to a child BG. If you’re deploying to the Master Org you can omit this parameter
  • <environment> - Specifies the Anypoint Environment for deployment. Be careful, this is case sensitive
  • <target> - The name of our RTF instance
  • <muleVersion> - The Mule runtime version on top of which the app would be deployed. Make sure you use a version supported by Runtime Manager, you can’t choose any version number in here. If not set, the latest Mule runtime version available in Runtime Manager is selected.
  • <server> - This is the authentication for the Mule Maven Plugin. With the server tag, Maven will use the credentials stored in the settings.xml. Make sure the value in this tag corresponds to the id of the server tag in the settings.xml where we configured the credentials of our Connected App.
  • <applicationName> - The display name for the app in Runtime Manager. We’re picking up the value from the name property defined at the beginning of the POM file
  • <replicas> - The number of replicas to be provisioned for the app in RTF

Run the commands

Once we’ve set up all the information for the Mule Maven Plugin we’ll use Maven commands to deploy our app. We need to do it in two steps


Step 1: Publish to Exchange

Open a terminal from the root folder of the Mule Project. For that, in Anypoint Studio, right-click on the project name > Show In > System Explorer. That will open the root folder of your project. From there, open a terminal and run the following command:

mvn clean deploy

This will publish the app to Exchange (it won’t deploy it to Runtime Manager)


You can verify the asset has been successfully uploaded by going to your Exchange. Exchange does not show the Application artifacts directly, but we can type the following URL in our browser: https://anypoint.mulesoft.com/exchange/?show=all&type=app

Step 2: Deploy to Runtime Manager

Once our app is published to Exchange then we’ll run another Maven command, this time explicitly calling the deploy goal of the Mule Maven Plugin with the -DmuleDeploy flag: 

mvn clean deploy -DmuleDeploy

This will deploy the app to Runtime Manager


Head over to Anypoint Runtime Manager and verify that your app has been uploaded and it’s up & running.

Configure the Mule Maven Plugin (Advanced)

Now that we’ve learnt how to deploy to Runtime Fabric with a basic configuration let’s now explore more options we can set up with the mule maven plugin to have more control of the deployment.
Here’s an example with an advanced configuration of the plugin:

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>${mule.maven.plugin.version}</version>
  <extensions>true</extensions>
  <configuration>
    <runtimeFabricDeployment>
      <uri>https://anypoint.mulesoft.com</uri>
      <muleVersion>${app.runtime}</muleVersion>
      <server>anypoint-exchange-v3</server>
      <applicationName>${project.name}</applicationName>
      <target>RTF-GON</target>
      <environment>Sandbox</environment>
      <provider>MC</provider>
      <replicas>2</replicas>
      <businessGroupId>2a619cd1-7f0c-4ab5-84d8-31fd3630ff77</businessGroupId>
      <properties>
        <http.port>8081</http.port>
      </properties>
      <secureProperties>
        <secret.key>${secret.key}</secret.key>
      </secureProperties>
      <deploymentSettings>
        <enforceDeployingReplicasAcrossNodes>true</enforceDeployingReplicasAcrossNodes>
        <updateStrategy>rolling</updateStrategy>
        <forwardSslSession>false</forwardSslSession>
        <clustered>true</clustered>
        <lastMileSecurity>false</lastMileSecurity>
        <resources>
          <cpu>
            <reserved>20m</reserved>
            <limit>1500m</limit>
          </cpu>
          <memory>
            <reserved>700Mi</reserved>
          </memory>
        </resources>
        <http>
            <inbound>
                <publicUrl>myapp.example.com</publicUrl>
            </inbound>
        </http>
        <persistentObjectStore>true</persistentObjectStore>
        <jvm>
            <args>-XX:MaxMetaspaceSize=500m -XX:MaxRAMPercentage=60.0</args>
        </jvm>
        <generateDefaultPublicUrl>true</generateDefaultPublicUrl>
        <disableAmLogForwarding>true</disableAmLogForwarding>
      </deploymentSettings>
    </runtimeFabricDeployment>
  </configuration>
</plugin>

Let’s see in detail the added parameters:

Properties and Secure Properties

We can set up Runtime Manager properties for our Mule application using these two elements in the plugin configuration. 
  • <properties> Properties defined under this element will be visible from the settings of the app in Runtime Manager. To define properties you need to follow the syntax <key>value</key> as in this example.
  • <secureProperties> - Properties defined in this element will be encrypted before storing them in Runtime Manager and won’t be visible from the app settings in Runtime Manager. To define them we follow the same syntax as before - <key>value</key> as in this example.


Deployment settings parameters

The configuration of the plugin for RTF provides the top element <deploymentSettings>, under which we can define the following parameters:
  • <enforceDeployingReplicasAcrossNodes> - When set to true, forces Runtime Manager to deploy each replica of the app in a different node of the RTF cluster to provide high availability. By default is set to false.
  • <updateStrategy> - With this parameter we can control how updates and re-deployments of the app are performed. We can choose between two values:
    • rolling - New replicas will be created in parallel with the old ones with the new app version. When the new ones are ready the old ones are destroyed. This allows for zero-downtime but requires additional resources during the process.
    • recreate - Old replicas are terminated before (re)deployment of new ones. This method is quicker and does not require additional resources but makes the app unavailable during the process.
            The default value is Rolling
  • <forwardSslSession> - If true, it enables the SSL forwarding. The default value is false
  • <clustered> If true, it enables clustering across two or more replicas of the app. This requires at least two replicas. The default value is false.
  • <lastMileSecurity> - If true, it enables Last Mile Security for the app. HTTPS connections will be terminated at the app, not at the ingress of RTF. The default value is false
  • <resources> - In this section we control the CPU and memory to be provisioned to each replica of our app, the same way we would do that from the graphical UI. For the CPU we can provide the values for reserved and limit. We need to make sure that the limit is always equal or higher than the reserved value.
  • <http><inbound> - This section corresponds to the options in the Ingres tab in Runtime Manager
    • <publicURL> - URL of the app, we can provide multiple comma-separated values. The URLs provided must be URLs previously configured as endpoints of the ingress controller(s).
  • <persistentObjectStore> - Configures the application to use a persistent object Store. Make sure that you’ve provisioned a Persistence Gateway for RTF. If not, check out this post on How to set up a Persistence Gateway for Mulesoft Runtime Fabric
  • <jvm> - Specifies JVM arguments to pass to Runtime Fabric when deploying the application. Use spaces to separate each argument.
  • <generateDefaultPublicUrl> - If true, RTF will generate a Public endpoint within the default ingress controller.
  • <disableAmLogForwarding> - When this is set to true, application logs are not sent to Anypoint Monitoring. The default value is false.


References

Tags

You may like these posts

Previous Post Next Post