Nav

About Load Balancer Mapping Rules

The load balancer configuration is defined by a list of Mapping Rules which describe how input URL should be translated into calls to different CloudHub apps.
Mapping rules are attributes of the load balancer’s SSL endpoint.
When you create a mapping rule, you need to specify a certificate CN. Omitting the [certificateName] parameter adds the mappings to the default endpoint.

When creating a simple matching rule, one input address is literally matched to the defined output: the endpoint of one of your applications.
Instead of using literal matchings you can also use a Pattern to match a variable-like input text to an endpoint.

By using proxy rules, you can map a domain or subdomain to one of your Mule applications that run in CloudHub

Using Patterns in Mapping Rules

A pattern is a string that defines a template for matching an input text. Whatever is placed into curly brackets ({ }) is treated like a variable. These variables can contain only letters (a-z) and cannot contain any other characters, such as digits, slashes, etc. The variable values can contain the following characters ‘a-z0-1.&?-_’ but no slashes.

For example, you can literally bind two hostnames for redirect:


         
      
1
‘app.example.com’ ->  application: `app` URI: `/example’

Or you can define a pattern to hold the input value:


         
      
1
‘example.com/{mypattern}’ -> application: `app-{mypattern}` URI: /data

The example above causes that both ’example.com/bookings’ and ‘example.com/sales’ match to app-bookings/data and app-sales/data respectively, as the variable mypattern holds these values.
For input=”bookings.example.com”, the pattern can be resolved by assigning mypattern=”bookings” and for input=`sales.example.com, the pattern is resolved to assign `mypattern=”sales”

Depending on your design, you can choose to leverage your internal redirects to your endpoints using patterns or simply literal mappings.

Note that currently patterns in the application URI are not supported.

Creating Mapping Rules

A mapping rule is a set of fields that define an Input URL, and a set of fields that describe the Output URL.

  • The input URL is described using a URI parameter which can be specified by the user:

    1. URI - a String or Pattern that describes the Input URI.

      The input URL follows the main load balancer’s domain (This value should remain constant for the same load balancer)

  • The Output URL is specified by two fields.

    1. appName - Output the application name where the request will be forwarded to.

    2. appURI - the URI string that is passed to the resolved application.

Both input and output URLs can be defined using patterns or literal Strings.

Mapping rules are attributes of the load balancer’s SSL endpoint, which is identified by the certificate name.
When you create a mapping rule, you need to specify a certificate CN. Omitting the [certificateName] parameter adds the mappings to the default endpoint.

If your SSL endpoint sets a wildcard certificate, and you want to use the subdomain portion in a mapping rule, you can use the pre-defined {subdomain} variable.

The rule which is defined first has high priority against other ones defined after it. This means that the first matched rule will be applied.
You can create, view and delete existing rules using the mappings add, mappings describe and mappings remove commands respectively.

Mapping Rule Examples

The table below contains some mapping rule examples:

Given that the external load balancer domain name depends on the unique name you assign to it, assume that the load balancer in these examples is lb-demo.

By default, your load balancer listens to external requests on HTTPS and communicates internally with your worker over HTTP. If you configured your Mule application within the VPC to listen on HTTPS, make sure you set upstreamProtocol to HTTPS when creating the mapping list using the load-balancer mappings add command.

URL Mapping

You can pass the app name as an input URI and map it directly to the app name in CloudHub:

Rule # Input URL Output URL

URI

appName

appURI

0

/{app}/

{app}

/

This rule maps lb-demo.lb.anypointdns.net/{app} to {app}.cloudhub.io.
{app} being a pattern for application name you choose to pass.

Host Mapping

If you have a wildcard certificate (like *.example.com), you can use the ´subdomain´ variable to map any subdomain:

Rule # Input URL Output URL

URI

appName

appURI

0

/

{subdomain}

/

This rule automatically maps any request passed to a subdomain of example.com to the corresponding appName. For example:

  • Passing api.example.com would redirect to api.cloudhub.io

  • Passing application.example.com is mapped to application.cloudhub.io.

The same applies for the Subject Alternative Names (SANs) of your SSL Endpoints.
If you have different SANs configured for a certificate’s common name, you can use the ´subdomain´ variable to map the subdomain portion of your domain name to your application. For this to work, however, your applications need to have the same name as the common portion of your domain name.

For example, having:

  • Two deployed applications:

    • dev-app

    • qa-app

  • And an SSL endpoint with the Subject Alternative Names:

    • dev.example.com

    • qa.example.com

  • The mapping rule:

    Rule # Input URL Output URL

    URI

    appName

    appURI

    0

    /

    {subdomain}-app

    /

Then, this rule would map the subdomain part of your domain name to the application name:

  • Passing dev.example.com redirects to dev-app.cloudhub.io.

  • Passing qa.example.com redirects to qa-app.cloudhub.io.

1:1 Mapping

If you have only one application, you can map the literal app name.

Rule # Input URL Output URL

URI

appName

appURI

0

/

myApp

/

This maps your default load balancer lb-demo.lb.anypointdns.net directly to your app in Cloudhub myApp.cloudhub.io.

Indexing the Priority of Rules

When creating a mapping rule, you need to assign an index to it to define the rule’s priority order.
A rule defined first, at index 0 has higher priority against other rules defined after it. The higher the index assigned, the less priority the mapping rule has.

Every rule must have a priority defined. It is highly recommended to pay attention to each rules’ order when creating them, and multiple rules might override each other.

Ordering and Prioritizing Rules

You can set the order of your mapping rules when creating them using the cloudhub load-balancer mappings add command in the Anypoint-CLI by specifying an index value.

When using the API to create a rule, you can not specify a priority order, but you can send a PATCH request later to the load balancer endpoint anypoint.mulesoft.com/cloudhub/api/organizations/{orgid}/loadbalancers/{loadbalancerId} and update your rules expressions with an order index, to match your needs based on the order logic explained above.

The load balancer ID is provided to you when you create it.
You can also perform a GET request to your endpoint /organizations/{orgid}}/loadbalancers` to get the ID.