Routing rules for Liberty dynamic routing

You can use routing rules in Liberty dynamic routing to customize exactly which servers are used to handle specific requests.

By default, dynamic routing balances load requests across all servers that can handle the request. To override the default behavior, you must configure routing rules. Routing rules can route requests to specific server resources, redirect requests, or reject requests.

If you deploy the same application to two different clusters, you can use routing rules to direct requests from a particular set of client IP addresses to one of the clusters and the rest of the requests to the other cluster.
If you deploy the same application in multiple collectives, you can use routing rules to send the requests only to the first collective, unless no servers are available in the first collective, then send requests to servers in the second collective.

Important: When you route to multiple collectives, routing rules are read from only one of the collectives. Intelligent Management for web servers reads routing rules only from the collective that is specified by the RoutingRulesConnectorClusterName property of the <IntelligentManagement> stanza in the plugin-cfg.xml file. The value of the RoutingRulesConnectorClusterName property is initialized with the name of the first collective specified by the ‑‑collectives option of the dynamicRouting command that created the plugin-cfg.xml file. Add your routing rules to the collective controllers in the collective specified by the RoutingRulesConnectorClusterName property of the <IntelligentManagement> stanza in the plugin-cfg.xml file.

Match expression and actions

Routing rules provide a match expression and an action. The match expression is applied to each request. When a request matches the match expression, the action that is specified by the rule is performed for that request. Match expressions examine various properties of the request such as the URI, headers, cookies, parameters, and client IP address. The action that is taken is to either reject, redirect, or permit the request.

Routing rules have an order number that is assigned to each rule. The rules are evaluated from lowest order number to highest. The first rule that matches a request determines how the request is handled. If no rule is matched, the request is balanced across all available servers that can handle the request.

If the action type of a rule is to reject the request, then the applicable HTTP return code is specified. The reject code must be one of the rejection codes that are supported by the web server.

If the action type of a rule is to redirect the request, then the redirection location is specified.

If the action type of a rule is to permit the request, the destinations where the request can be sent are specified. The destinations specify the set of all servers to choose when load balancing the request. From the set of destinations, only the servers that can best handle the request are used. Failover destinations can also be specified. Servers in a failover destination are only used if all servers in a primary destination are not available. Destinations can be specified as either clusters or servers.

By default, when a request has session affinity, server selection is based on affinity. If an affinity server is found, routing rules are not used. To enable routing rules to override affinity selection, the overrideAffinity attribute can be added to the <routingRules> element of the server.xml file. See Configuring routing rules for Liberty dynamic routing.

Cluster destination

A cluster destination is specified with a collective name and a cluster name. Either part of the cluster destination can use wildcard (*) characters. For example, if a cluster destination is specified as cluster=collective1,*, then servers in any cluster in collective1 can be used. If a cluster destination is specified as cluster=*,cluster1, then servers in cluster1 in any collective can be used.

Server destination

A server destination is specified with a collective name, a host name, a user directory, and a server name. All parts of the server destination can use wildcard characters. For example, if a server destination is specified as server=collective1,*,*,*, then any servers in collective1 can be used. If a server destination is specified as server=*,*,*,server1, then server1 in any collective can be used.

Routing rules evaluation

Before any routing rules are applied, Intelligent Management for Web Servers determines the best set of destinations to serve a request. The best set of destinations are those servers with web applications whose virtual host, context root, and servlet mappings best match the request. Routing rules can restrict the destinations that are used for routing to a subset of the full set of best destinations. Routing rules cannot cause a destination to be chosen that is outside of the original set of best destinations.

For example, suppose that the following conditions exist:

ApplicationA has context root /A/* and is installed on clusterA.
ApplicationAB has context root /A/B/* and is installed on clusterAB.

Under the conditions, routing rules evaluates requests as follows:

Both applications can serve the request /A/B/myservlet. However, because /A/B/* context root is a better match for /A/B/myservlet than /A/* context root, requests for /A/B/myservlet are always routed to clusterAB.
A routing rule that matches a request for /A/B/myservlet can be used to restrict destinations to a subset of servers in clusterAB, but cannot be used to select servers in clusterA, which is never chosen as a match for this request.