How to deploy to Cloudhub 2.0 with the Mule Maven Plugin

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 Cloudhub 2.0. 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 Cloudhub 2.0:

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 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 Cloudhub 2.0. 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 Environments in a particular organization
View Organization

Under Design Center:

Design Center Developer

Under Runtime Manager:

Read Applications
Create Applications
Delete Applications
Manage Application Data

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 Cloudhub 2.0 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 Cloudhub 2.0 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

If you already added the distributionManagement element in the previous post you can skip this step. If not, make sure you add a distributionManagement element pointing to Exchange V3 at the end of the pom file. This is how Maven will know where to find your Private Exchange repository.

<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 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 CH2.0
Advanced - Where we will explore the optional parameters of the plugin to fine-tune our deployment to CH2.0

Configure the Mule Maven Plugin (Basic)

For a basic configuration, we’d add this configuration to the Mule Maven Plugin:

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>${mule.maven.plugin.version}</version>
    <extensions>true</extensions>
    <configuration>
        <cloudhub2Deployment>
            <uri>https://anypoint.mulesoft.com </uri>
            <provider>MC</provider>
            <businessGroupId>${project.groupId}</businessGroupId>
            <environment>[YOUR_ANYPOINT_ENV]</environment>
            <target>[YOUR_CH20_PRIVATE_SPACE]</target>
            <muleVersion>4.6.0</muleVersion>
            <server>anypoint-exchange-v3</server>
            <applicationName>${project.name}</applicationName>
            <replicas>1</replicas>
            <vCores>0.1</vCores>
        </cloudhub2Deployment>
    </configuration>
</plugin>

Where:

<cloudhub2deployment> Tells the plugin to deploy to CH2.0
<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 CH2.0
<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> - Specifies the shared/private space in CH2.0 where we will be deploying the app. For the Private Space we need to provide the name of the PS. For a shared space, we need to provide the region from the list:

Cloudhub-US-East-1
Cloudhub-US-East-2
Cloudhub-US-West-1
Cloudhub-US-West-2
Cloudhub-EU-West-1
Cloudhub-EU-West-2
Cloudhub-AP-Southeast-1
Cloudhub-AP-Southeast-2
Cloudhub-AP-Northeast-1
Cloudhub-SA-East-1
Cloudhub-EU-Central-1
Cloudhub-CA-Central-1

<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, the plugin will use the credentials stored in the settings.xml file. 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
<replicas> - The number of replicas to be provisioned for the app
<cores> - The size of the vCores for the replicas

Run the commands

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)

Once we’ve learnt how to deploy to CH2.0 with a basic configuration let’s now explore more options we can set up with the mule maven plugin.
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>
        <cloudhub2Deployment>
            <uri>https://anypoint.mulesoft.com </uri>
            <provider>MC</provider>
            <businessGroupId>${project.groupId}</businessGroupId>
            <environment>Development</environment>
            <target>GON-PS</target>
            <muleVersion>4.6.0</muleVersion>
            <server>anypoint-exchange-v3</server>
            <applicationName>${project.name}</applicationName>
            <replicas>2</replicas>
            <vCores>0.1</vCores>
            <properties>
                <http.port>8081</http.port>
            </properties>
            <secureProperties>
                <secret.key>${secret.key}</secret.key>
            </secureProperties>
            <deploymentSettings>
                <enforceDeployingReplicasAcrossNodes>true</enforceDeployingReplicasAcrossNodes>
                <updateStrategy>rolling</updateStrategy>
                <clustered>true</clustered>
                <http>
                    <inbound>
                        <publicURL>https://myapp.anypoint.com</publicURL>
                        <lastMileSecurity>true</lastMileSecurity>
                        <forwardSslSession>true</forwardSslSession>
                    </inbound>
                </http>
                <generateDefaultPublicUrl>true</generateDefaultPublicUrl>
                <disableAmLogForwarding>false</disableAmLogForwarding>
            </deploymentSettings>
            <integrations>
                <services>
                    <objectStoreV2>
                        <enabled>true</enabled>
                    </objectStoreV2>
                </services>
            </integrations>
        </cloudhub2Deployment>
    </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 CH2.0 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 Availability Zone of the deployment Region 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 allow for zero-downtime but require 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

<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.
<http><inbound> - This section corresponds to the options in the tab

<publicURL> - URL of the app, we can provide multiple comma-separated values. The URLs provided must be URLs previously configured as endpoints for the Private Space.
<lastMileSecurity> - If true, it enables Last Mile Security for the app. HTTPS connections will be terminated at the app, not at the ingress of CH2.0. The default value is false
<forwardSslSession> - If true, it enables the SSL forwarding. The default value is false
<generateDefaultPublicUrl> - If true, CH2.0 will generate a Public endpoint within *.cloudhub.io domains. We only use this parameter with Private Spaces. With Shared Spaces this is created by default.

<disableAmLogForwarding> - When this is set to true, application logs are not sent to Anypoint Monitoring. The default value is false.

Integrations

With the <integrations> element we control the use of the Object Store for the app. If set to true the deployment will use the OSv2.