Oracle Cloud Infrastructure Documentation

Request Routing Management

Learn how to route incoming requests to various backend sets.

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 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. These 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.

    Note

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

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

    Note

    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.

Note

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.

See Hostname Management for more information on how to create and manage virtual hostnames.

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 behavior 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 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.

See Routing Policy Management for more information on creating and managing routing policies.

Path Route Sets

Note

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

A path route is a string that the load balancer matches against an incoming URI to determine the appropriate destination backend set. 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 set includes all path route rules that define the data routing for a particular listener.

Note the following about path route sets:

  • You cannot use asterisks in path route strings.

  • You cannot use regular expressions.

  • Path route string matching is case-insensitive.

  • 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.

Note

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.

See Path Route Set Management for more information on creating and managing path route sets.

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.

See Rule Set Management for more information on creating and managing rule sets.

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 following configuration examples show how incoming routes URLs are routed:

  • 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.