How to distribute your API traffic with MuleSoft load balancers

November 27 2020


MuleSoft provides two types of load balancers, shared load balancer, and dedicated load balancer to distribute API traffic deployed on the MuleSoft cloud workers. Shared load balancer is multi-tenant and shared with other customers. Dedicated load balancers enable you to deploy and configure one or more custom load balancers within your Anypoint Virtual Private Cloud (Anypoint VPC). The aim of load balancing is to optimize the use of API instances available, maximize throughput, minimize response time, and avoid overload of any single API instance. Instead of using a single API instance, load balancing takes advantage of multiple resources, by providing high availability and reliability.

 1. Shared load balancer

MuleSoft provides a default shared load balancer (SLB) that is available in all environments. The shared load balancer sits outside the customer’s Anypoint VPC and provides basic functionality, such as TCP load balancing for external-facing API calls. The shared load balancer supports TLS 1.1 and TLS 1.2. SLB routes the HTTPS traffic to port 8082 and HTTP traffic to port 8081.

SLBs are shared between customers and have lower rate limits that ensure platform stability. If an API exceeds the rate limit for a shared load balancer, the load balancer returns a 503 service unavailable response. If your applications need rate limits of over 100 transactions per second it is recommended to use a dedicated load balancer even though the SLB can handle higher rate limits and MuleSoft regularly monitors and scales these limits as necessary by region. 

However, SLBs don’t allow you to configure custom SSL certificates or proxy rules. For APIs needing higher than 100 transactions per second or configuring two way SSL client authentication, etc. you must use dedicated load balancers.

 2. Dedicated load balancer

MuleSoft offers dedicated load balancers (DLBs) as an optional component of Anypoint Platform that enable you to route external and VPC-internal HTTP and HTTPS traffic to multiple Mule applications. To use DLBs in your environment, you must first create an Anypoint VPC. You can associate multiple environments within the same Anypoint VPC and the dedicated load balancer. 

Here are some examples of what you can do with DLBs:

  • Dedicated load balancers enable you to route traffic among the different MuleSoft cloud workers that run your internal or external facing applications or APIs.
  • Define SSL configurations to provide custom certificates and optionally enforce two-way SSL client authentication. 
  • Configure proxy rules that map your applications to custom/vanity domains. This enables you to host your applications under a single domain. 
  • Create mapping rules that can support routing for different versions of an API. 
  • You can configure the IP address CIDR to allow access to your DLB. It could be limited to private IP addresses within the VPC or IP Addresses limited to the customer network or open it up to everyone on the internet.

Routing external requests

A CloudHub dedicated load balancer provides an alternative domain name to route HTTP requests to Mule applications listening on port 8091 and HTTPS requests to Mule applications listening on port 8092. You can also use mapping rules to rename requests to the dedicated load balancer to a different Mule application name.

The dedicated load balancer exposes an external domain name that resolves to two public IP addresses which are accessible from outside your Anypoint VPC network. lb-name is the name you gave the load balancer when you created it:

  • (US control plane)
  • (GovCloud control plane)
  • (EU control plane)

Routing internal requests

The dedicated load balancer has an internal domain name that is used by applications and clients within the Anypoint VPC. The internal domain uses the following naming convention internal-<lb-name>

Each Dedicated Load Balancer has a DNS A record that resolves to the two public IP addresses of the two instances.

If you want your load balancer to manage all connections to your application but do not want your default domain name for your application publicly exposed, then each application must listen on HTTP port 8091 or 8092. Alternatively, you can create a custom mapping policy to redirect outside requests from your load balancer to your specific application.

Public & private DNS/IP addresses

Public DNS/IP:

  • The Public IP’s are by default, static IP’s. This is optional in the DLB config, and can be changed to use dynamic IPs.
  • You can find the public IP addresses in the Runtime Manager User Interface in the Load Balancer section.
  • The public DNS name is <lb-name> Resolution of this DNS will point to the Public IP addresses of the hosts for the DLB.

Private DNS/IP:

  • The Private/Internal IP addresses are always dynamic IPs, and there is no option to make them static.
  • The Private IPs of the DLB change every time the DLB instance is redeployed. It can be redeployed as a result of changes made by you via the API/UI as well as maintenance.
  • The private DNS name is internal-<lb-name> Resolution of this DNS will point to the private IP addresses of the hosts for the DLB.

Constraints when using Private DNS/IP from your data center over VPN:

  • If your firewall restricts access to specific DLB private IP addresses, then this could be an issue. The private IP address of the DLB is not static, it will change if there are changes made to the DLB or if the DLB is restarted. 
  • Your DNS cache implementation and DNS TTL can cause an outage when the DLB internal IP changes for the reasons described above.
  • If the internal IP lives in your DNS cache on the Client or your Internal DNS, beyond when the IP changes on the DLB, then all services that access that DLB endpoint will be unable to access it until the TTL expires.

Create mapping rules

You can create a mapping rule to rename the Mule application, so it can be accessed through a different domain name. A dedicated load balancer hides this naming complexity within your corporate DNS domain name. 

Every rule must have a priority defined. The first rule in the list has a higher priority than rules lower in the list. The DLB always uses the first rule that matches, regardless of whether a more exact match appears later in the list. When creating rules, pay attention to the order for each rule to avoid multiple rules overriding each other.

You can use pattern matching, URL mapping, subdomain mapping and literal 1:1 mapping for multiple applications to change the input path to output path.

Rule to hold the patterns:

In this example, both and match app-bookings/data and app-sales/data respectively, because the variable myPattern holds these values.

Rule for app name:

This rule maps requests to{app}, redirecting them to {app} The {app} pattern matches any application name that you pass in the inbound request.

Rules for literal 1:1 static mappings:

Rule to use the subdomain variable:

The subdomain variable to map the subdomain portion of your domain name to your application.

The example below includes:

  • Two deployed applications:
    • dev-app
    • qa-app
  • An SSL endpoint with these SANs configured:

Subdomain mapping rule

  • This rule maps the subdomain part of your domain name to the application name:
    • redirects to
    • redirects to

Certificates for SSL and client authentication

Secure sockets layer (SSL) is the standard security technology for establishing an encrypted link between a client and a load balancer. A dedicated load balancer must have at least one certificate associated with it. To configure an SSL endpoint for your load balancer to serve clients, provide a certificate, and private key pair for your load balancer. A load balancer can have multiple and independent SSL endpoints, each identified by its server certificate common name. Instead of using a wildcard certificate, which permits any subdomain application name to pass through the DLB, you can specify which subdomain names to allow (i.e. To do this, you must configure those SANs for a certificate’s common name. You can add additional certificates to a DLB using Runtime Manager or the command-line interface.

The certificate needs the following files:

  • Public key file
    A PEM file that includes both the server certificate and the intermediate CA certificate, for example, example-com-crt.pem
  • Private key file
    A PEM file that contains a passphrase-less private key, for example, example-com-private-noencrypt.pem

To enable two-way authentication you have to upload the client certificate containing the public key. The load balancer will authenticate the client when it is making a request to the load balancer. 

If at least one client authentication certificate is provided for the SSL endpoint, the load balancer passes the client certificate data to the API using these HTTP headers:

  • X-SSL-Client-Verify:
    Returns one of:
      The client is verified only after SUCCESS.
    • NONE when the certificate is not present
    • FAILED when other validation problems occur
  • X-SSL-Client-DN: Contains the full distinguished name of the client certificate
  • X-SSL-Issuer: Contains the full distinguished name of the issuing certificate
  • X-SSL-Client-Serial: Contains the serial number used by the CA to identify the client

You have an option to select client certificate validation and set it mandatory to forward the request to upstream APIs or optional to forward the request anyway. With the setting set to optional you have an option to use the the X-SSL-Client-Verify header value to implement the security within the APIs selectively based on the use case.

Scaling the Number of Workers

Each DLB by default runs in a HA configuration with two workers. However it is possible to increase the number of workers to 4,6,8 when creating DLB.

Vanity Domain

Vanity Domain URLs use your brand name to give the user an understanding of where the link will lead them, therefore, increasing link trust and is easier to remember than a generic short URL or a long URL. To send a request to the DLB, it is recommended to set a CNAME record pointing to <lb name>, rather than hardcoding the DLB’s public IP address, even though it is static. In addition, you can set a CNAME record in your corporate DNS nameserver to mask the domain to your company’s “vanity” domain.

It is a good practice to use load balancers as they can provide security, high availability, reliability, and distribution of application traffic across multiple instances for your APIs. For more information, check out our documentation on Anypoint load balancers.