A corner-stone of professional software engineering is automation, which helps eliminate human error, reduce unintended variability, and increase reproducibility. In this article, we demonstrate how to automate the deployment of a Mule application to CloudHub, while customizing the default rendering of the Mule app in Anypoint Visualizer.
Mule apps are typically built and packaged with Maven using the Mule Maven plugin (MMP). This is fully supported by Anypoint Studio, which maintains many aspects of Maven build configurations. In addition to building and packaging Mule apps, MMP also supports their deployment to many Mule runtime targets, including CloudHub, Runtime Fabric, and standalone Mule servers (either directly or via Anypoint Runtime Manager).
This article uses content from the recently released
MuleSoft Training course “Anypoint Platform Development:
Production-Ready Development Practices.
In this article, we extend the standard MMP configuration generated by Studio to automate deployment to CloudHub. This requires us to address the most important specifics of the CloudHub deployment model. In a second step, we optimize this MMP configuration to automatically make the most of Anypoint Visualizer, an intuitive and powerful application network visualization and insight generation tool available in Anypoint Platform.
Building Mule apps with the Mule Maven plugin
For this demonstration, we will create a new, simple Mule app called “mysystemapi” with Studio 7.4.2 for Mule runtime 4.2.2 and MMP 3.3.6. This Mule app is an implementation of a System API, which the app therefore exposes. Studio generates the following MMP configuration in pom.xml
1 <plugin>
2 <groupId>org.mule.tools.maven</groupId>
3 <artifactId>mule-maven-plugin</artifactId>
4 <version>${mule.maven.plugin.version}</version>
5 <extensions>true</extensions>
6 <configuration>
7 </configuration>
8 </plugin>This configuration supports building and packaging this Mule app into an artifact named “mysystemapi-1.0.0-SNAPSHOT-mule-application.jar” in the target directory. (The artifact name is determined by <artifactId/>, <version/> and <packaging/> in pom.xml.) This artifact is a deployable Mule app archive, and could be manually uploaded to Runtime Manager for deployment to CloudHub (or other deployment targets). Here, however, we want to automate the deployment to CloudHub.
Extending the Mule Maven plugin configuration for deployment to CloudHub
To deploy to CloudHub using MMP, we must add at a minimum the following details to the MMP configuration:
1 <configuration>
2 <cloudHubDeployment>
3 <server>cloudhub</server>
4 <environment>dev</environment>
5 <muleVersion>${app.runtime}</muleVersion>
6 <workerType>MICRO</workerType>
7 </cloudHubDeployment>
8 </configuration>This configuration makes use of several defaults pertaining to the CloudHub deployment model, such as:
- Deployment via the MuleSoft-hosted Anypoint Platform control plane in the U.S.
- Directly to the master organization rather than a business group of the chosen Anypoint Platform organization (see below).
- Deployment to the CloudHub runtime plane in the us-east-1 region.
- Deployment to one CloudHub worker.
- Transient (non-persistent) VM queues.
- Default deployment timeout.
- CloudHub application name (deployment name) of “mysystemapi,” that is, the value of <artifactId/>.
- No properties set on the deployed Mule app.
Overall, this determines the main load-balanced (though only to one worker) fully-qualified domain name (FQDN) for this Mule app to be “mysystemapi.us-e1.cloudhub.io.”
In real-world deployment scenarios, it is typically necessary to explicitly set most of these values, for example:
1 <configuration>
2 <cloudHubDeployment>
3 <server>cloudhub</server>
4 <businessGroup></businessGroup>
5 <environment>${env}</environment>
6 <region>us-east-2</region>
7 <muleVersion>${app.runtime}</muleVersion>
8 <workers>1</workers>
9 <workerType>MICRO</workerType>
10 <objectStoreV2>true</objectStoreV2>
11 <persistentQueues>true</persistentQueues>
12 <applicationName>${name}</applicationName>
13 </cloudHubDeployment>
14 </configuration>These properties and their value ranges are documented here.
As a best practice, most of these values should be supplied via Maven properties. Here, we have done this only for the Studio-generated app.runtime and the newly introduced properties env and name.
Of particular interest here is the setting of the CloudHub application name via name. CloudHub requires this name to be unique amongst all CloudHub deployments performed through the chosen Anypoint Platform control plane. At the time of this writing (January 2020), MuleSoft hosts two general-purpose instances of the Anypoint Platform control plane, one in the US and one in the EU. The US control plane, which is implicitly used in the above configuration, supports deployments to CloudHub runtime planes in most regions of the world. This means that a CloudHub application name must be unique across all these regions, across all Anypoint Platform organizations and business groups, and across all their Anypoint Platform environments (dev, test, prod, etc.).
For this reason, CloudHub application names are typically constructed to include elements identifying the organization and environment. For example:
1 dev
2 myorg-${project.artifactId}-${env}
The env Maven property defaults to dev but can be overridden at deployment time. For example, to deploy to the test environment:
1 mvn -DmuleDeploy deploy -Denv=test
With this configuration and deployment command, the FQDN for this Mule app becomes “myorg-mysystemapi-test.us-e2.cloudhub.io.”
When executing this deployment with this configuration, MMP looks-up a matching <server/> entry in the Maven settings.xml file (typically located under $HOME/.m2/) to retrieve Anypoint Platform credentials:
1 <settings>
2 <servers>
3 <server>
4 <id>cloudhub</id>
5 <username>myuser</username>
6 <password>mypass</password>
7 </server>
8 </servers>
9 </settings>MMP uses these credentials to authenticate against the Anypoint Platform control plane. Because the username is uniquely associated with an Anypoint Platform organization, MMP deploys the Mule app to that organization. (Maven supports securing passwords in settings.xml, but this is not the subject of this article.)
Once the deployed Mule app has started processing requests, Visualizer can show the app as a node in the application network of our Anypoint Platform organization. This would require manual interaction with the Visualizer UI in Anypoint Platform — which we want to obviate through automation in the next step.
Adding customizations for Visualizer to the Mule Maven plugin configuration
For Visualizer to show a Mule app, it requires metrics about runtime traffic to be sent by that Mule app to the Anypoint Platform control plane. Because this incurs a slight performance overhead, it is turned-off by default. It could be turned-on manually in the Visualizer UI, but it’s more reproducible to do so by setting a Mule app property during deployment.
By default, Visualizer shows Mule apps deployed to CloudHub using their CloudHub application name “myorg-mysystemapi-test,” as shown in the following figure. But, Visualizer only shows CloudHub deployments from the current Anypoint Platform organization, making the inclusion of the organization prefix (myorg-) redundant. Furthermore, Visualizer explicitly supports Anypoint Platform environments and can filter its display by environment, so that the environment suffix (-test) is redundant. Making the most concise Visualizer display name for our Mule app “mysystemapi.” Concise naming is important to increase information density in the typically busy application network renderings created effortlessly by Visualizer. The display name of a Mule app could be overridden manually in the Visualizer UI, but it is preferable to do so automatically by setting a Mule app property.
Visualizer can assign Mule apps to layers, if it is given the information on what layer a given Mule app belongs. By default, Visualizer knows the Experience, Process, and System layers, but other layers can be defined. Because our Mule app is a System API, the assignment to the System layer is immutable during the lifetime of this app. This assignment could be made manually in the Visualizer UI, but it is less error-prone to do so by setting a Mule app property.
This leads us to the following refined MMP configuration:
1 <configuration>
2 <cloudHubDeployment>
3 ...
4 <properties>
5 <anypoint.platform.config.analytics.agent.enabled>
6 true
7 </anypoint.platform.config.analytics.agent.enabled>
8 <anypoint.platform.visualizer.displayName>
9 ${project.artifactId}
10 </anypoint.platform.visualizer.displayName>
11 <anypoint.platform.visualizer.layer>
12 System
13 </anypoint.platform.visualizer.layer>
14 </properties>
15 </cloudHubDeployment>
16 </configuration>Using this configuration, Visualizer always displays our Mule app as shown in the following figure, without the need for any manual tuning:
Summary
We have extended the Maven build configuration of a Mule app generated by Studio to support automated deployment to CloudHub. In doing so we added configuration addressing the details of the CloudHub deployment model. We then customized this configuration further to automatically show this Mule app in Visualizer, with a concise name and in the correct layer.
This and similar topics related to developing Mule apps with an eye towards automation, reproducibility, and monitoring are covered in the recently released MuleSoft Training course “Anypoint Platform Development: Production-Ready Development Practices.”
