Contact Us 1-800-596-4880
  1. Homepage
  2. CloudHub
  3. Dedicated Load Balancers
  4. Configure SSL Endpoints and Certificates

  5. Mapping Rules

Dedicated Load Balancer Mapping Rules

The CloudHub dedicated load balancer (DLB) routes requests from clients to Mule apps deployed within the VPC. Mapping rules enable you to forward requests received by the DLB (using the HTTP Host header to identify the matching rule) to a different Mule application name and domain.

You can either define mapping rules when you create the DLB, or you can define and add them to an existing DLB using Runtime Manager, the command-line interface (CLI), or the CloudHub API.

When you create a simple matching rule, one input address matches the defined output: the endpoint of an application. Instead of using literal matchings, you can use a pattern to match a variable, such as input text to an endpoint.

The order of the rules determines their priority. The first rule in the list that matches is applied.

If you don’t define any mapping rules, the DLB creates and uses a default mapping rule. You can change the default mapping rule later.

Create Mapping Rules

Mapping rules are attributes of the load balancer’s SSL endpoint, which is identified by the certificate Common Name (CN).

The certificate is associated when you create mapping rules:

  • Runtime Manager

    You define mapping rules within a certificate definition.

  • CLI or CloudHub API

    You must specify a certificate CN.

    If you omit the certificate name, the mappings are added to the default endpoint.

Create Mapping Rules in Runtime Manager

To create mapping rules in an SSL endpoint for a DLB in Runtime Manager:

  1. From Anypoint Platform, select Runtime Manager.

  2. Select Load Balancers in the left menu.

  3. Click a load balancer name, and then click a certificate name.

  4. In the URL Mapping Rules section, click Add New Rule:

    the *Add New Rule* icon and the fields required to create a mapping rule
    Figure 1. The screenshot shows (1) the Add New Rule icon and (2) the fields required to create a mapping rule.

  5. Complete the fields:

    • Input Path (inputUri)

      The URI that the client requests: for example, /{app}/

      The input URI is appended to the host header of the load balancer.

    • Target App (appName)

      The name of the CloudHub application that processes the request: for example, {app}-example

    • Output Path (appURI)

      The URI string to pass to the app: for example, /

      The output path cannot contain patterns.

    • Protocol (upstreamProtocol)

      The protocol on which the application listens:

      • http (port 8091)

      • https (port 8092)

      • ws WebSockets (port 8091)

      • wss WebSockets over SSL/TLS (8092)

      By default, the 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, set Protocol to https when you create the mapping rule list.

The DLB uses the values in the fields and the client request to generate the path that is sent to the target app.

For example, if the client request is <domain.com>/hello/world/ and the mapping rules fields are set to the following:

  • Input Path: /hello/

  • Target App: myApp1

  • Output Path: /test/

The DLB uses the value of the output path (/test/), removes the section that matches the input path from the client request (/hello/), and appends the rest (/world/) to the client request. The DLB then sends the resulting path (/test/world/) to the target app (myApp1).

You can use either patterns or literal strings to define the input path. For the output path, you can use only literal strings.

Create a Mapping Rule Using the CLI

To create a mapping rule in a DLB using the CLI:

cloudhub load-balancer mappings add [options] <name> <index> <inputUri> <appName> <appUri> [certificateName]

See cloudhub load-balancer mappings add.

Create a Mapping Rule Using the CloudHub API

To create a mapping rule in a DLB using the CloudHub API:

anypoint.mulesoft.com/cloudhub/api/organizations/{orgid}/loadbalancers/{loadbalancerId}

See CloudHub API.

Use Patterns in Mapping Rules

A pattern is a string that defines a template for matching an input text. The value in curly brackets ({ }) is treated as a variable:

  • Variable names can contain only lowercase letters (a-z) and no other characters.

  • Variable values can contain the characters a-z0-1.&?-_, but can’t contain slash characters (/).

DLBs don’t support patterns in the Output Path (appURI).

URL Mapping

You can pass the app name as the Input Path and map it directly to the app name in CloudHub:

Rule # Input Path Target App Output Path Protocol

1

/{app}/

{app}

/

http

This rule maps requests to lb-demo.lb.anypointdns.net/{app}, redirecting them to {app}.cloudhub.io. The {app} pattern matches any application name that you pass in the inbound request.

Host Mapping

If your SSL endpoint sets a wildcard certificate (such as *.example.com), you can use the subdomain variable to map any subdomain:

Rule # Input Path Target App Output Path Protocol

1

/

{subdomain}

/

https

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

  • Passing api.example.com redirects to api.cloudhub.io.

  • Passing application.example.com maps to application.cloudhub.io.

You can also use the subdomain variable with the Subject Alternative Names (SANs) of your SSL endpoints.

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. To do this, you must configure those SANs for a certificate’s common name. You can use the subdomain variable to map the subdomain portion of your domain name to your application.

This example includes:

  • Two deployed applications:

    • dev-app

    • qa-app

  • An SSL endpoint with these SANs configured:

    • dev.example.com

    • qa.example.com

  • Mapping rule:

    Rule # Input Path Target App Output Path Protocol

    1

    /

    {subdomain}-app

    /

    https

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

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

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

Use a Literal 1:1 Mapping

Instead of using a pattern, you can map literal app names. In this case, the rules must match the applications exactly.

This rule maps the default load balancer lb-demo.lb.anypointdns.net directly to the myApp.cloudhub.io app in CloudHub:

Rule # Input Path Target App Output Path Protocol

1

/

myApp

/

http

This rule matches the dev-misc-myhellotest-v1-myapp app if the input URI is /misc/myhellotest/v1/ping but not /misc/myhellootest/v1/ping:

Rule # Input Path Target App Output Path Protocol

1

/{layera}/{domaina}/v{versiona}/

dev-{layera}-{domaina}-{versiona}-myapp

/api/

http

You can also use literal 1:1 mappings for multiple applications by changing the Input Path to be static instead of a defined pattern:

Rule # Input Path Target App Output Path Protocol

1

/v1/applicationX

application-x

/api/

http

2

/v1/applicationY

application-y

/api/

http

3

/v2/applicationx

application-x-v2

/api/

http

Mapping Rule Priority

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.

In the following example, the /api/v1/secondapp URL maps to the default-app app:

Priority Input Path Target App Output Path Protocol

1

/api/v1/

default-app

/api/v1/

http

2

/api/v1/secondapp/

second-app

/api/v1

http

For the rule to match only second-app, the rule priority must be:

Priority Input Path Target App Output Path Protocol

1

/api/v1/secondapp/

second-app

/api/v1

http

2

/api/v1/

default-app

/api/v1/

http

Change the Priority of Mapping Rules in Runtime Manager

To change the priority of mapping rules in Runtime Manager:

  1. From Anypoint Platform, select Runtime Manager.

  2. Select Load Balancers in the left menu.

  3. Click a load balancer name, and then click a certificate name.

  4. In the URL Mapping Rules section, hover over the rule to display the handle:

    Handle to use to reorder a mapping rule
    Figure 2. The arrow shows the handle to use to reorder a mapping rule.

  5. Click and drag the handle to move the rule up or down in the list.

  6. Click Done Editing.

Change the Priority of Mapping Rules Using the CLI

To specify the mapping rule priority when creating a mapping rule with the CLI, use the index value. The rule at index 0 has the highest priority. The higher the index assigned, the lower the priority.

See cloudhub load-balancer mappings add.

Change the Priority of Mapping Rules Using the CloudHub API

When using the API to create a mapping rule, you cannot specify a priority order. The new rule is appended to the list. You can update the order of the rules later by sending a PATCH request to the load balancer endpoint:

anypoint.mulesoft.com/cloudhub/api/organizations/{orgid}/loadbalancers/{loadbalancerId}

To determine the load balancer ID, perform a GET request to your endpoint:

/organizations/{orgid}/loadbalancers

See Also