Oracle Cloud Infrastructure Documentation

Managing Request Routing

This topic describes how to manage your load balancer's request routing. For information about managing load balancers, see Managing Load Balancers.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: For a typical policy that gives access to load balancers and their components, see Let network admins manage load balancers.

Also, be aware that a policy statement with inspect load-balancers gives the specified group the ability to see all information about the load balancers. For more information, see Details for Load Balancing.

If you're new to policies, see Getting Started with Policies and Common Policies.

Routing Incoming Requests

The Load Balancing service enables you to route incoming requests to various backend sets. You can assign virtual hostnames to a listener  or create route rules .

Virtual Hostnames

When used in concert with A records you create in your DNS system, you can assign virtual hostnames to any listener you create for your load balancer. Hostnames associated with a listener correspond to the backend sets of that listener. Those backend sets route traffic to specific backends which host different applications. Some advantages of virtual hostnames include:

  • A single associated IP address. Multiple hostnames, backed by DNS entries that you create in your nameservers, can point to the same load balancer IP address.
  • A single load balancer. You do not need a separate load balancer for each application.
  • A single load balancer shape. Running multiple applications behind a single load balancer helps you manage aggregate bandwidth demands and optimize utilization.
  • Simpler backend set management. Managing a set of backend servers under a single resource simplifies network configuration and administration.

You can define exact virtual hostnames, such as "app.example.com", or you can use wildcard names. Wildcard names include an asterisk (*) in place of the first or last part of the name. When searching for a virtual hostname, the service chooses the first matching variant in the following priority order:

  1. Exact name match (no asterisk), such as app.example.com.

  2. Longest wildcard name that begins with an asterisk, such as *.example.com.

    Tip

    Prefix wildcard names might require a wildcard certificate for HTTPS sites.

  3. Longest wildcard name that ends with an asterisk, such as app.example.*.

    Tip

    Suffix wildcard names might require a multi-domain Subject Alternative Name (SAN) certificate for HTTPS sites.

You do not need to specify the matching pattern to apply. The pattern is inherent in the asterisk position, that is, starting, ending, or none.

The following considerations apply to virtual hostnames:

  • You cannot use regular expressions.
  • To apply virtual hostnames to a listener, you first create one or more virtual hostnames associated with a load balancer.
  • Virtual hostname selection priority is not related to the listener's configuration order.
  • You can apply a maximum of 16 virtual hostnames to a listener.
  • You can associate a maximum of 16 virtual hostnames with a load balancer.
Tip

The virtual hostnames feature supports HTTP and HTTPS listeners only, but does not support TCP listeners.
Note

Default Listener

If a listener has no virtual hostname specified, that listener is the default for the assigned port.

If all listeners on a port have virtual hostnames, the first virtual hostname configured for that port serves as the default listener.

Routing Policies

Request routing policies allow you to route ingress traffic requests based on whether they match certain conditions you define. These rule conditions can use boolean and near-match operations. The rules are evaluated in the order you define and the evaluation stops at the first match. You can attach one such request routing rule set to your HTTP or HTTPS listeners. A well-formed request routing rule is made up of one or more match conditions and a single corresponding route action. You can create multiple routing rules. If an incoming request doesn't match any of the rules you created, the request is routed to a default backend set attached to the listener.

For HTTP headers, query data parameters, and cookies, the following match types are supported:

  • Contains: <key> equals <value>
  • Does not contain: <key> equals <value>
  • Exists: <key>
  • Does not exist: <key>

Routing policies also support rules that match against request URL paths. This is similar to path route sets, but offers different match options. The following match types are supported in routing policies for path matching:

  • Is: An exact match of the path, such as /videos or /images.
  • Is not: Any path that doesn't exactly match the specified path.
  • Starts with: A match happens if the path begins with the input value. If the parameter provided was /videos then a request for /videos/images would still produce a match.
  • Does not start with: A match happens if the path begins with anything other than the parameter provided. If the parameter provided was /videos then a request for /images/stills would still produce a match.
  • Ends with: A match happens if the path ends with the parameter. If the parameter provided was /videos then a request for both /images/videos or /previews/videos would both produce a match.
  • Does not end with: A match happens if the path ends with anything other than the parameter provided. So if the parameter provided was /videos then a request for /videos/images would produce a match.
Note

Path route sets will be retired on Thursday, 24 March 2022. When path route sets are retired, these options will take the place of path route sets rules.

The only supported routing rule action is:

  • Route to a specific backend set: This choice routes the matched requests to a backend set that you specify.

To create a routing policy using the console see To Create a Routing Policy. To create a routing policy using the API, see Using the API.

Path Route Sets

Note

Path route sets will be retired on Thursday, 24 March 2022.

Route to specific backends using a virtual hostname, or a routing policy.

Some applications have multiple endpoints or content types, each distinguished by a unique URI path. For example, /admin/, /data/, /video/, or /cgi/. You can use path route rules to route traffic to the correct backend set without using multiple listeners or load balancers.

A path route is a string that the Load Balancing service matches against an incoming URI to determine the appropriate destination backend set.

  • You cannot use asterisks in path route strings.
  • You cannot use regular expressions.
  • Path route string matching is case-insensitive.
Important

Browsers often add an ending slash to the path in a request. If you specify a path such as /admin, you might want to configure the path both with and without the trailing slash. For example,/admin and /admin/.

A path route rule consists of a path route string and a pattern match type.

  • Pattern match types include:

    • EXACT_MATCH

      Looks for a path string that exactly matches the incoming URI path.

      Applies case-insensitive regex:

      ^<path_string>$

    • FORCE_LONGEST_PREFIX_MATCH

      Looks for the path string with the best, longest match of the beginning portion of the incoming URI path.

      Applies case-insensitive regex:

      <path_string>.*

    • PREFIX_MATCH

      Looks for a path string that matches the beginning portion of the incoming URI path.

      Applies case-insensitive regex:

      ^<path_string>.*

    • SUFFIX_MATCH

      Looks for a path string that matches the ending portion of the incoming URI path.

      Applies case-insensitive regex:

      .*<path_string>$
  • Path route rules apply only to HTTP and HTTPS requests and have no effect on TCP requests.

A path route set includes all path route rules that define the data routing for a particular listener.

  • You can specify up to 20 path route rules per path route set.
  • You can have one path route set per listener. The maximum number of listeners limits the number of path route sets you can specify for a load balancer.

Rule Priority

The system applies the following priorities, based on match type, to the path route rules within a set:

  • For one path route rule that specifies the EXACT_MATCH type, no cascade of priorities occurs. The listener looks for an exact match only.
  • For two path route rules, one that specifies the EXACT_MATCH type and one that specifies any other match type, the exact match rule is evaluated first. If no match is found, then the system looks for the second match type.

  • For multiple path route rules specifying various match types, the system applies the following priority cascade:

    1. EXACT_MATCH
    2. FORCE_LONGEST_PREFIX_MATCH
    3. PREFIX_MATCH or SUFFIX_MATCH
  • The order of the rules within the path route set does not matter for EXACT_MATCH and FORCE_LONGEST_PREFIX_MATCH. The system applies the priority cascade no matter where these match types appear in the path route set.
  • If matching cascades down to prefix or suffix matching, the order of the rules within the path route set DOES matter. The system chooses the first prefix or suffix rule that matches the incoming URI path.

Virtual Hostname and Path Route Rules Combinations

Virtual hostnames and path route rules route requests to backend sets. Listeners with a virtual hostname receive priority over the default (no hostname) listener. The following example shows the results of a simple routing interaction.

The example system includes three listeners and one path route set:

Listener 1

  • Virtual hostname: none
  • Default backend set: A
  • Path route set: PathRouteSet1

Listener 2

  • Virtual hostname: captive.com
  • Default backend set: B
  • Path route set: PathRouteSet1

Listener 3

  • Virtual hostname: wild.com
  • Default backend set: C
  • Path route set: PathRouteSet1

Path Route Set

  • Path route set name: PathRouteSet1

    • Exact match on path string /tame/ routes to backend set B.
    • Exact match on path string /feral/ routes to backend set C.

The example configuration routes incoming URLs as follows:

http://animals.com/ is routed to backend set A
  • Virtual hostname animals.com matches Listener 1.
  • Path / is not an EXACT_MATCH for any path route string in PathRouteSet1.
http://animals.com/tame/ is routed to backend set B
  • Virtual hostname animals.com matches Listener 1.
  • Path /tame/ is an EXACT_MATCH for path route string /tame/ in PathRouteSet1.
http://animals.com/feral/ is routed to backend set C
  • Virtual hostname animals.com matches Listener 1.
  • Path /feral/ is an EXACT_MATCH for path route string /feral/ in PathRouteSet1.
http://captive.com/ is routed to backend set B
  • Virtual hostname captive.com matches Listener 2.
  • Path / is not an EXACT_MATCH for any path route string in PathRouteSet1.
http://captive.com/tame/ is routed to backend set B
  • Virtual hostname captive.com matches Listener 2.
  • Path /tame/ is an EXACT_MATCH for path route string /tame/ in PathRouteSet1.
http://captive.com/feral/ is routed to backend set C
  • Virtual hostname captive.com matches Listener 2.
  • Path /feral/ is an EXACT_MATCH for path route string /feral/ in PathRouteSet1.
http://wild.com/ is routed to backend set C
  • Virtual hostname wild.com matches Listener 3.
  • Path / is not an EXACT_MATCH for any path route string in PathRouteSet1.
http://wild.com/tame/ is routed to backend set B
  • Virtual hostname wild.com matches Listener 3.
  • Path /tame/ is an EXACT_MATCH for path route string /tame/ in PathRouteSet1.
http://wild.com/feral/ is routed to backend set C
  • Virtual hostname wild.com matches Listener 3.
  • Path /feral/ is an EXACT_MATCH for path route string /feral/ in PathRouteSet1.

Using the Console

You can specify virtual hostnames and path route sets when you create or update a listener.

Creating Virtual Hostnames

To apply virtual hostnames to a listener, you first create one or more virtual hostnames. The virtual hostnames become a part of the load balancer's configuration. You then specify one or more virtual hostnames to use when you create or update a listener for the load balancer.

To create a virtual hostname
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Hostnames, and then click Create Hostname.

  4. In the Create Hostname dialog box, enter the following:

    • Name: Required. Specify a friendly name for the hostname. The name must be unique, and cannot be changed. Avoid entering confidential information.
    • Hostname: Required. Specify the virtual hostname. See Virtual Hostnames for a description of valid hostname construction and behavior.
  5. Click Create. The Work Request Submitted dialog box opens.
  6. To close the dialog box, click Close. To open the Work Requests page and view the status of the work request, click View All Work Requests.

After you create a virtual hostname, the name becomes available for use with the associated load balance. To apply the hostname, create or update a listener.

To update a virtual hostname
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Hostnames.
  4. For the hostname you want to edit, click the Actions icon (three dots), and then click Edit.

  5. In the Edit Hostname dialog box, enter your updates to the Hostname field.

    You cannot edit the Name field of an existing virtual hostname.

  6. Click Update. The Work Request Submitted dialog box opens.
  7. To close the dialog box, click Close. To open the Work Requests page and view the status of the work request, click View All Work Requests.
To delete a virtual hostname
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Hostnames.
  4. For the hostname you want to edit, click the Actions icon (three dots), and then click Delete. The Work Request Submitted dialog box opens.
  5. To close the dialog box, click Close. To open the Work Requests page and view the status of the work request, click View All Work Requests.
To Create a Routing Policy
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Routing Policies, and then click Create Routing Policy.
  4. Enter a Name for the routing policy rule set. A name is required. The name must be unique, and cannot be changed. The name cannot begin with a period and cannot contain any of these characters: ; ? # / % \ ] [. The name must start with an lower- or upper- case letter or an underscore, and the rest of the name can contain numbers, underscores, and upper- or lower-case letters.
  5. To create a rule in the rule set:

    1. Choose If All Match (peer conditions use a logical AND) or If Any Match (peer conditions use a logical OR). In rules with multiple conditions, this selection guides whether one or all stated conditions produce an action. There can be up to five rule conditions, and you can have up to five nested conditions within a top-level condition. There can be up to 200 conditions total in a policy. Nested conditions can't have further conditions nested within them.

    2. Each top-level condition has a type, a match style, and a final criteria.
      • Condition Type: The setting can be Path, Request Cookies, Request Header, URL Query, or Nested Match. The available fields for a condition change depending on the condition type.

        A Nested Match also has a Nested conditions match criteria for conditions nested within, allowing you to have a mix of AND and OR in a condition. Click +Another Nested Condition to add another nested condition within the group. You can only nest conditions one level deep.

      • The match style for Path can be: Is, Is not, Starts with, Does not start with, Ends with, or Does not end with. The match style for Request Header, Request Cookies, and URL Query can be: Contains, Does not contain, Exists, or Does not exist.
      • The final criteria depends on the Condition Type selected, and can be a URL String (All Path conditions use this) a Key:Value pair or simply a Key.
    3. Select the Action. If you choose Route to Backend Set, select the destination backend set from the list of available sets.
    4. To create another rule, click + Another Rule.
  6. You can also click Show Advanced Controls. An editing window opens where you can directly enter text to define rules using the Routing Policy Language.
  7. Click Next after you finish defining the rules.

    The next step is to confirm the order of the rules.

  8. In the right end of the order list row corresponding to that rule. Click the down arrow to see a summary of the conditions and actions set in a rule.
  9. To move a rule up or down in the policy order, click Reorder.
    1. Choose from among Move to Top, Move to Bottom, Move Up, or Move Down. The last two options shift that rule up or down by one position in the order
  10. When the routing policy rules are created and in the right order, click Create Routing Policy.

To use a routing policy, you must create a listener that uses the policy.

Creating Path Route Sets

To apply path route rules to a listener, you first create a path route set that contains the rules. The path route set becomes a part of the load balancer's configuration. You then specify the path route set to use when you create or update a listener for the load balancer. To remove a path route set from a listener, edit the listener and choose None as the Path Route Set option.

Note

Path route rules will be retired on: Thursday, 24 March 2022. Instead, use Routing policies.
To create a path route set
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Path Route Sets, and then click Create Path Route Set.

  4. In the Create Path Route Set dialog box, enter the following:

    • Name: Required. Specify a friendly name for the path route set. The name must be unique, and cannot be changed.

      The path route set name cannot begin with a period and cannot contain the characters ;, ?, #, %, /, \, [, or ].

      Avoid entering confidential information.

    • Path Route Rules

      • Order: Optional. If you have multiple path route rules, you can click the up or down arrows to move the corresponding rule.

        Tip

        The order of the rules within the path route set does not matter in most cases. However, if matching cascades down to prefix or suffix matching, the system chooses the first prefix or suffix rule that matches the incoming URI path.
      • Match Style: Required. The type of matching to apply to incoming URIs.
      • URL String: Required. The path string to match against the incoming URI path, for example /admin/.
      • Backend Set Name: Required. The name of the target backend set for requests where the incoming URI matches the specified path.
  5. (Optional) Click + Additional Rule to create another path route rule or click the red box to delete an existing rule. You can have up to 20 path route rules in a set.
  6. Click Create.

After you create a path route set, the set becomes available for use with the associated load balance. Create or update a listener to apply the path route set.

To update a path route set
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Path Route Sets.
  4. Click the name of the path route set you want to update, and then click Edit Path Route Rules.

  5. In the Edit Path Route Rules dialog box, edit the following as needed for each rule you want to change:

    • Order: Optional. If you have multiple path route rules, you can click the up or down arrows to move the corresponding rule.

      Tip

      The order of the rules within the path route set does not matter in most cases. However, if matching cascades down to prefix or suffix matching, the system chooses the first prefix or suffix rule that matches the incoming URI path.
    • Match Style: Required. The type of matching to apply to incoming URIs.
    • URL String: Required. The path string to match against the incoming URI path, for example /admin/.
    • Backend Set Name: Required. The name of the target backend set for requests where the incoming URI matches the specified path.
  6. (Optional) Click + Additional Rule to create another path route rule or click the red box to delete an existing rule. You can have up to 20 path route rules in a set.
  7. Click Save Changes.
To update a single path route rule
  1. Open the navigation menu, click Networking, and then click Load Balancers.
  2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.
  3. In the Resources menu, click Path Route Sets, and then click the name of the path route set you want to update.
  4. For the path route rule you want to edit, click the Actions icon (three dots), and then click Edit Path Route.

  5. In the Edit Path Route Rule dialog box, edit the following as needed for each rule you want to change:

    • Order: Optional. If you have multiple path route rules, you can click the up or down arrows to move the corresponding rule.

      Tip

      The order of the rules within the path route set does not matter in most cases. However, if matching cascades down to prefix or suffix matching, the system chooses the first prefix or suffix rule that matches the incoming URI path.
    • Match Style: Required. The type of matching to apply to incoming URIs.
    • URL String: Required. The path string to match against the incoming URI path, for example /admin/.
    • Backend Set Name: Required. The name of the target backend set for requests where the incoming URI matches the specified path.
  6. Click Save Changes.

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use these API operations to manage request routing.

Listener commands:

Routing policy commands:

Path route commands: