Nav

Customize Mule Runtime BuildPack

Customizing a BuildPack is an optional step when configuring Anypoint Platform for PCF. You can instead use the default Mule Runtime BuildPack, which includes Mule runtime 3.8.1.

Each buildpack in named following a specific format: mule_runtime_buildpack_<runtime_version_number> For example: mule_runtime_buildpack_3_8_1

Overview

This extension of the java-buildpack is a Cloud Foundry buildpack for running Mule applications. It is designed to run both traditional Mule Integration applications and APIs (gateways and implementations) on a Mule runtime (formerly known as Mule).

Installation

  1. Download the Mule Runtime Buildpack (zip file).

  2. Unzip the buildpack and customize files or configuration depend on requirement.

    Generate a runtime license digest using MuleSoft License Verifier service on your web browser:

    • Upload your Mule runtime license .lic file, obtained through the Customer Onboarding process, and click Verify button.

    • Download the digested license by clicking the Download digested license link and placing the generated muleLicenseKey.lic file in the resources/mule/conf directory (create directories if needed).

  3. Add additional resources

    The resources/mule directory replicates the Mule runtime directory structure. Files and directories in this location will be overlaid on the expanded runtime upon deployment. Typical resources to add include:

    • Custom shared libraries (jar files) in resources/mule/lib/user

    • Patches (jar files) in resources/mule/lib/user, resources/mule/lib/mule and resources/mule/plugins

    • Custom domains in resources/mule/domains

      Create the required directories as necessary. Refer to Mulesoft documentation or Support Portal Knowledge Base for specific details on using custom libraries and patches.

  4. Zip the buildpack with all the changes.

    • zip -r <buildpack.zip file> <buildpackdir>

  5. install your buildpack on your PCF environment**

    Install the buildpack on your PCF environment/space by executing:

    cf create-buildpack <BUILDPACK_NAME> <BUILDPACK_ZIP_PATH> <POSITION>.

    • If you are using anypoint-onpremise for managing your apps then <BUILDPACK_NAME> should be in format mule_runtime_buildpack_<runtime_version_number> - For example: mule_runtime_buildpack_3_8_1

      For example:

      cf create-buildpack mule_runtime_buildpack_3_8_1 mule-runtime-buildpack-3.8.1.zip 1 --enable.

Operation

Application Design and Configuration Considerations

Inbound HTTP Endpoints

When designing your applications, keep in mind that CloudFoundry will automatically allocate an internal port on the container linked to the routes defined on the CF Router for the application. This port is supplied to the application through the java property ${http.port}. This will be the only port on which your application will receive inbound traffic. Additionally, applications can only provide a single HTTP listener component.

Make sure your application DOES NOT provide the http.port variable on the mule-app.properties file, or configuration files loaded through Spring Properties Placeholders, as this overrides the port supplied through Cloud Foundry environment variables mechanims, preventing connectivity to your app once deployed.

Container Disk Size

Make sure you allocate more disk space than memory to your application, to be able to generate a JVM heap dump in case MuleSoft Support team requests it for diagnostics purposes.

Application Deployment

Application-Specific Configuration

Application-specific configuration is provided through Environment Variables. These can be supplied through the Cloud Foundry Apps Manager user interface, or through Application manifests files.

See a minimal example manifest.yml file below:


           
        
1
2
3
4
5
6
---
applications:
- name: simpleapi
  buildpack: mule_runtime_buildpack_3_8_1
  env:
    MYCUSTOM_ENV_VARIABLE: -mycustomflag=1234

Memory Allocation

The Anypoint Buildpack uses the JavaBuildpack memory heuristics to allocate memory for the different JVM memory spaces, up to the maximum memory allocated to the application through configuration.

Details about this process and the estimated proportions can be found here.

JVM-Specific Parameters

JVM-specific configuration parameters can be supplied through the JAVA_OPTS mechanism, either through:

  • a JAVA_OPTS [application environment variable](#application-specific-configuration),

  • the config/java_opts configuration file.

Applying Patches to Mule Runtime

Add MuleSoft patches (jar files) to the resources/mule directory structure as described [here](#application-specific-configuration).

Pay special attention to the version of the runtime that patches apply to, and ensure it matches the versions the buildpack will consider as defined on the user_config.yml file.

Integration with Third-Party Components

AppDynamics Integration

The Anypoint buildpack provides out-of-the-box integration with App Dynamics through the standard JavaBuildpack App Dynamics Extension. If the application has a bound custom service following naming conventions and pointing to an App Dynamics instace, the JVM will start with the appropriate flags to connect to it.

See more details aboud App Dynamics integration here

Integration with Other Components Supported by the Java Buildpack

Other components/agents that are originally supported by the official java-buildpack can be enabled through the config/components.yml file, uncommenting entries as appropriate. Although these components/agents should use the Java Buildpack standard extension mechanisms to provide required flags to the JVM, bear in mind that these components are not tested nor supported by MuleSoft.

Debugging and Troubleshooting

Debugging Buildpack Provisioning Process

Add a JBP_LOG_LEVEL=debug environment variable to generate verbose debugging output of the whole buildpack provisioning process, as described on section (#Application-specific-configuration). Debug information will be produced on the application logs.

JVM Diagnostics Information

If a runtime deployed on a Cloud Foundry environment through the builpack runs into issues, Mulesoft Support team will request a JVM heap dump or JVM thread dump for diagnostics purposes. In order to generate one, you need to log in the CF container running your application, use JDK tools to generate the dump, and upload the data through scp or sftp outside the CF env.

Make sure your application always has more disk space allocated than memory, to be able to store the dumps on the container transient storage filesystem and upload to an external SFTP or SSH server.

To perform this process, follow these steps:

  1. Log-in your application container through SSH**

    If your space configuration allows it, you can enable SSH access using the CF CLI:

    cf enable-ssh MY-APP

    Then you can log-in to the container through the following command:

    cf ssh MY-APP

    (If your space doesn’t allow SSH access, request it to a CF administrator or deploy the app on a space that allows it)

    More information on enabling SSH access can be found here: https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html

  2. Find JVM process PID

    You can determine the JVM process running the Mule runtime through the following command:

    $ PID=$(pgrep java)
  3. Produce the diagnostics data**

    You can use JDK toolkit to produce the diagnostics data Mulesoft Support team is requesting.

    For example, to produce a JVM heap dump with Oracle JDK use the following command:

$ /home/vcap/app/.java-buildpack/oracle_jre/bin/jmap -dump:format=b,file=heap.bin $PID

+ To produce a JVM heap dump with Open JDK, use the following command:

 $ /home/vcap/app/.java-buildpack/open_jdk_jre/bin/jmap -dump:format=b,file=heap.bin $PID

+ For example, to produce a JVM thread dump with Oracle JDK use the following command:

$ /home/vcap/app/.java-buildpack/oracle_jre/bin/jstack -dump:format=b,file=heap.bin $PID

+ To produce a JVM thread dump with Open JDK, use the following command:

 $ /home/vcap/app/.java-buildpack/open_jdk_jre/bin/jstack -dump:format=b,file=heap.bin $PID
  1. Send the diagnostics data to an external SSH/SFTP server**

    You can use scp or sftp to upload the dumps to an external server, from where you can provide it to Mulesoft Support team:

    scp heap.bin user@externalserver.myorg.com:/home/user

Providing Diagnostics Information for MuleSoft Support Team

If you need to report an issue with the Mule runtime or the buildpack itself through MuleSoft support process, you’ll be required to provide the following information: