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  you should 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:

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. Each hostname can correspond to a backend set, that backend set can route traffic to specific backends which will 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.

Path Route Rules

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, there is no cascade of priorities. 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. Under the Core Infrastructure group, go to Networking and 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. Under the Core Infrastructure group, go to Networking and 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. Under the Core Infrastructure group, go to Networking and 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.

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.

To create a path route set
  1. Open the navigation menu. Under the Core Infrastructure group, go to Networking and 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. Under the Core Infrastructure group, go to Networking and 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. Under the Core Infrastructure group, go to Networking and 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.