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 a Load Balancer.

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. 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

You can assign virtual hostnames to any listener you create for your load balancer. Each hostname can correspond to an application served from your backend. Some advantages of virtual hostnames include:

  • A single associated IP address. Multiple hostnames, backed by DNS entries, 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
http://animals.com/tame/ is routed to backend set B
http://animals.com/feral/ is routed to backend set C
http://captive.com/ is routed to backend set B
http://captive.com/tame/ is routed to backend set B
http://captive.com/feral/ is routed to backend set C
http://wild.com/ is routed to backend set C
http://wild.com/tame/ is routed to backend set B
http://wild.com/tame/ is routed to backend set C

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
To update a virtual hostname
To delete a virtual hostname

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
To update a path route set
To update a single path route rule

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: