Dedicated Load Balancer Mapping Rules | MuleSoft Documentation
# 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** :
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}
```

## 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**  
---|---|---|---|---  
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**  
---|---|---|---|---  
{subdomain}  
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`
  * An SSL endpoint with these SANs configured:
    * `dev.example.com`
    * `qa.example.com`
  * Mapping rule:
Rule # | **Input Path** | **Target App** | **Output Path** | **Protocol**  
---|---|---|---|---  
{subdomain}-app  


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`.
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`
  * An SSL endpoint with these SANs configured:
    * `dev.example.com`
    * `qa.example.com`
  * Mapping rule:
Rule # | **Input Path** | **Target App** | **Output Path** | **Protocol**  
---|---|---|---|---  
{subdomain}-app  


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**  
---|---|---|---|---  
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**  
---|---|---|---|---  
/{layera}/{domaina}/v{versiona}/ |  dev-{layera}-{domaina}-{versiona}-myapp  
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**  
---|---|---|---|---  
/v1/applicationX |  application-x  
/v1/applicationY |  application-y  
/v2/applicationx |  application-x-v2  
## 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  
---|---|---|---|---  
default-app  
/api/v1/secondapp/  
For the rule to match only `second-app`, the rule priority must be:
Priority | Input Path | Target App | Output Path | Protocol  
---|---|---|---|---  
/api/v1/secondapp/  
default-app  
### 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:
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
  * CloudHub Dedicated Load Balancer
  *   *