Using new features of Intelligent Management for Web Servers with Traditional WebSphere Application cells

You must install a web server that is supported by the Intelligent Management for Web Servers feature of the web server plug-in for WebSphere Application Server, such as the IBM HTTP Server. Install a 9.0.0.2 or higher web server plug-in for WebSphere Application Server, then install interim fix PI73118 before trying to route to the same application in multiple cells or trying to use routing rules.

• 1. Download and install the latest version of the IBM Installation Manager. For more information on installing IBM Installation Manager, see Installing Installation Manager and preparing to install the product.
  
  2. Use Installation Manager to access online product repositories to install the Web Server Plug-in for WebSphere Application Server and the needed interim fix (PI73118) for the new feature.
  
  3. Use Installation Manager to access online product repositories to install the needed interim fix for the new feature onto your WebSphere Application Server Network Deployment installation. The interim fixes PI72200 and PI72201 must both be installed and can be applied to WebSphere Application Server Network Deployment versions 9.0.0.2 or 8.5.5.11.

Concepts for routing to multiple cells:

Intelligent Management for Web Servers enables routing of HTTP requests to members of WebSphere Application Server cells without requiring an administrator to regenerate the WebSphere plug-in configuration file when the environment changes. When servers, cluster members, applications, or virtual hosts are added, removed, started, stopped, or modified; the new information is dynamically delivered to the WebSphere plug-in. Requests are routed based on up-to-date information.

Intelligent Management for Web Servers routes application requests to all application instances when the application is deployed in multiple cells. Previously, when routing to multiple cells, a particular application could exist in only one of the cells.

To use routing rules to route to multiple cells, each cell must have a different cell name.

Use the procedure at Configuring Intelligent Management for web servers to set up routing from the Intelligent Management enabled WebSphere plug-in to applications in multiple cells. There is no change in the procedure to configure multi-cell routing, however, you now have the capability to install the same application in multiple cells.

Multi-cell routing with Application Edition rules

Application Edition routing rules are completely different from web server routing rules. See Application edition manager concepts. Application Edition routing rules are set on a particular application. See Creating routing policies for application editions. If the same application is installed in multiple cells, the Application Edition routing rules can be different in each cell. The Intelligent Management enabled WebSphere plug-in will find all web modules that can best service a request across all cells. When choosing a specific server to route to, the IM enabled plug-in will honor the Application Edition routing rules specific to each cell.

Example:

• Cell1 and Cell2 contain ApplicationA with edition1 and edition2 both active.

  Application Edition routing rules have been configured in both cells to permit some subset of the requests to go to each edition.

  When a request for ApplicationA is routed to Cell1, the Application Edition routing rules in Cell1 will be used to decide which edition to route to. When a request for ApplicationA is routed to Cell2, the Application Edition routing rules in Cell2 will be used to decide which edition to route to.

Application Edition routing rules can also specify that certain requests can be rejected or redirected. When choosing how to handle a request which matches Application Edition routing rules in multiple cells, the IM enabled plug-in will prefer to route to those cells where the request is ‘permitted’ to go to an application edition. If all cells have Application Edition routing rules that only redirect or reject the request, the IM enabled plug-in will prefer to redirect the request. If multiple cells have redirect rules with different redirect locations, all redirect locations will be used at some point. A request will be rejected due to Application Edition routing rule action only if all cells have Application Edition routing rules that reject the request. If multiple cells have different reject error codes, all error codes will be used at some point.

Web server routing rules are evaluated along with application edition rules. Both the routing rules and the edition rules must be satisfied for the specified action to be performed.

Concepts for routing to a subset of available servers using routing rules

By default, dynamic routing load balances 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.

You can use routing rules in WebSphere Application Server to customize exactly which servers will be used to handle specific requests.

Examples:

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

  2. If you deploy the same application in multiple cells, you can use routing rules to send the requests only to the first cell, unless no servers are available in the first cell, then send requests to servers in the second cell.

Important: When routing to multiple cells, routing rules can be specified in only one of the cells. Intelligent Management for Web Servers will read routing rules only from the cell 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 cell used to generate the plugin-cfg.xml file. Make sure you add your routing rules to the cell 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 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 taken is to either reject, redirect, or permit the request.

Routing rules have an order number 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 load-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 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 unavailable. 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 allow routing rules to override affinity selection, the overrideAffinity property must be set to “true” by using the setWebServerRoutingRulesProperty AdminTask.

Note: Application Edition routing rules always override affinity if the affinity server is not among the permit destinations of the application edition rule.

 

Cluster destination

A cluster destination is specified with a cell 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=cell1/*, then servers in any cluster in cell1 can be used. If a cluster destination is specified as cluster=*/cluster1, then servers in cluster1 in any cell can be used.

 

Server destination

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

 

How Routing Rules are evaluated

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

Example:

• ApplicationA has context root /A/* and is installed on clusterA.

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

  Both applications can serve the request /A/B/myservlet. However, since /A/B/* context root is a better match for /A/B/myservlet than /A/* context root, requests for /A/B/myservlet will always be 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, since clusterA will never be chosen as a match for this request.

Procedure to route to a subset of available servers using routing rules

Web server routing rules are managed (created, listed, updated, deleted) using AdminTask commands. The available commands are listed with AdminTask.help('WebServerRoutingRuleCommands'). See the Reference section for a complete description of the commands available to manage Web server routing rules. To add a new routing rule, use AdminTask.addWebServerRoutingRule(…). The parameters needed for the addWebServerRoutingRule command are described next.

• 1. Determine the value of the expression parameter that will be used to select the rule. The value of the expression parameter is typically an operand followed by an operator followed by some constant value. The exception is the percentage operand, which does not support an operator. Table 1 shows the operands that are supported. Table 2 shows the operators that are supported.

  Table 1. matchExpression operands. Include an operand in a matchExpression definition.
  Operand	Syntax	Description
  Client IPV4	clientipv4	The IP address of the client that uses the Internet Protocol version 4 (IPv4) dotted quad address type of n.n.n.n.
  Client IPV6	clientipv6	The Internet Protocol version 6 (IPv6) 128-bit address type of x:x:x:x:x:x:x:x that follows Request for Comments 1924 (RFC 1924) of the client computer.
  Cookie name	cookie$name	A cookie name. For example, the expression cookie$My_Cookie_Name='My_Cookie_Value' tests a request to see if it contains a cookie named My_Cookie_Name with a My_Cookie_Value value. To test for the presence or absence of a particular cookie, use one of the following expressions: cookie$MyCookieName IS NOT NULL cookie$MyCookieName IS NULL
  Header name	header$name	A header name and value. For example, the expression header$Host='localhost' tests a request to see if it contains an HTTP host header with a locahost value. To test for presence or absence of the host header, use one of the following expressions: header$Host IS NOT NULL header$Host IS NULL
  Percentage	percentage$val	The percentage operand evaluates to true some percentage of the time. For example, percentage$50 evaluates to true on average 50% of the time.
  Query parameter	queryparm$name	A header name and value. For example, the expression queryparm$timezone='EST' tests a request to see if the request contains an HTTP query parameter named timezone with an EST value. To test for the presence or absence of a query parameter, use one of the following forms: queryparm$timezone IS NOT NULL queryparm$timezone IS NULL
  URI	uri	Uniform Resource Identifier
  Virtual host	virtualhost	Virtual host target of the request
  Virtual port	virtualport	Virtual port target of the request

  Table 2. matchExpression operators. Include an operator in a matchExpression definition as needed.
  Operator	Syntax	Description
  Equals	=	The equality operator expresses a case-sensitive match.
  Equals ignore case	EQUALSIGNORECASE	Identical to 'String = String' except that the case of the strings is ignored. For example, 'ABC' EQUALSIGNORECASE 'abc' evaluates to true and ('ABC' = 'abc') evaluates to false.
  IN	IN	Expresses an operand with multiple values in a single expression. For example, for an operand called port, to express that the port value can be any or all of the integers 9080, 9090, and 9091, the expression fragment is port IN (9080,9090,9091). How the values inside the parentheses are expressed depends on the data type. For example, if port is an integer, the correct syntax is the value without quotation marks. If port is a string, the correct syntax is port IN ('9080','9090','9091').
  Is not null	IS NOT NULL	Evaluates to true if the specified operand exists.
  Is null	IS NULL	Evaluates to true if the specified operand does not exist.
  Like	LIKE	Expresses pattern matching for string operand values. The value must contain the wildcard character percent sign (%) in the position where the pattern matching starts. For example: a. The host LIKE %blanca expression matches the word blanca or any other word that ends in blanca. b. The host LIKE blanca% expression matches the word blanca or any other word that starts with blanca. c. The host LIKE %blanca% expression matches the word blanca or any word that contains blanca.
  Like ignore case	LIKEIGNORECASE	Identical to 'string LIKE string' except that the case of the strings is ignored.
  Like in	LIKEIN	Evaluates whether a string exists in a list of strings. For example, string likein (string1%, string2%, string3%, etc.) evaluates to true if string matches one or more of the strings in the parentheses. In this example, the parentheses contain three string values.

  
  
  An example expression parameter could be:
   

  -expression “URI LIKE ‘/AppA%’” or -expression “queryparm$myparm = ‘test’”

  
  You can use AND, OR, NOT, and parenthesis to form complex sets of operators and operands for evaluation.
  
  
  • Example:

    -expression “(URI LIKE ‘/AppA%’ AND queryparm$myparm = ‘test’) or clientipv4 = \‘127.0.0.1\’”

  
  Be Aware: The and, or, not you use must be specified as lowercase.
  
  2. Determine the value of the actionType parameter that specifies what action to take when the rule expression is matched.

  The four possible actionTypes are permit, permitMM, redirect, or reject. Specify exactly one of the four possible action types for each routing rule. The permit actionType is used to allow requests to be routed to a set of available servers. The permitMM actionType allows routing to servers even if the chosen server is in maintenance mode. The reject actionType rejects a request with a specific return code. The redirect actionType redirects the request to a specific URL.

  
  
  • Example:

    -actionType permit or -actionType permitMM or -actionType reject or -actionType redirect

  3. For permit or permitMM actionTypes, determine the destinations where requests that match the rule will be sent. Use the routingLocations parameter to specify the destinations to route to.

  
  
  • a. Specify the primary set of destinations to route to when the rule expression is matched.

    Use one or more cluster or server destinations, separated by the ampersand (&) symbol.

    
    
    • To specify a server-typed endpoint, specify server= followed by a three-part server specification, with parts delimited by a forward slash:

      Example:

       

      server=cell_name/node_name/server_name

      • • cell_name is the name of the cell where the server is a member.
        • hode_name is the node where the server is located.
        • server_name is the server name.
      To specify a cluster-typed endpoint, specify cluster= followed by a two-part cluster specification, with parts delimited by a forward slash:

      Example:

       

      cluster=cell_name/cluster_name

      • • cell_name is the name of the cell where the cluster is defined
        • cluster_name is the cluster name.
      All parts of a server or cluster destination specification can use the wildcard character (*) to match any string.

      Example:

      -routingLocations “cluster=cell1/cluster1&cluster=cell1/cluster2” or -routingLocations “server=cell1/node1/server1&server=cell1/node2/server2” or -routingLocations “cluster=cell1/cluster1&server=cell1/*/server1”

    b. Optionally specify sets of failover destinations that will be used to route requests if all primary destinations are unavailable. Separate sets of failover destinations using the vertical bar (|) symbol. Multiple sets of failover destinations can be specified. The sets of destinations will be looked at in order, until an available server is found.
    
    
    • Example:

      -routingLocations “cluster=cell1/*|cluster=cell2/*”

      In the previous example, if a server that can handle the request is available in cell1, the server in cell1 is chosen. If there are no servers in cell1 available that can handle the request, a server in cell2 that can handle the request is chosen.
  4. For the redirect actionType specify the location to redirect to. Use the redirectURL parameter to specify the location.
  
  
  • Example:

    - redirectURL "http: //some.other.destination"

  5. For the reject actionType specify the response code to return. Set the errorCode parameter to the HTTP response code to use when the request matches the rule. The code must be an error code that the web server supports.
  
  
  • Example

    -errorCode "500”

  6. Determine the order number of the rule. Use the order parameter to specify where the rule fits in relation to other rules. Each order number can only be used once. Rules are evaluated from lowest order number to highest. The first rule with a matching expression is used. It is recommended to leave gaps between the order numbers so that new rules can be inserted without having to renumber existing rules.

  7. Add the routing rule to a web server. Use the parameters determined in the previous steps to call the addWebServerRoutingRule method of AdminTask.

  
  
  • Example:

    AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 -nodeName node1 -order 100 –expression “URI LIKE \’/AppA%\’” -actionType permit –routingLocations “cluster=cell1/*|cluster=cell2/*”]’)

  8. Optionally specify the overrideAffinity property for routing rules. By default, a request that has affinity to a particular server will be sent to that server, even if the request matches a routing rule that does not contain the affinity server as a destination. If the overrideAffinity property is set to “true”, then selecting a destination that is in a matched rule will take precedence over selecting the affinity server. If the affinity server satisfies the matched rule, the affinity server will be chosen, even if the affinity server is in a failover set of endpoints.
  The overrideAffinity property applies to all routing rules, the overrideAffinity property cannot be set on a per rule basis.
  • Example:
     

    AdminTask.setWebServerRoutingRulesProperty('[-serverName webserver1 -nodeName node1 -propertyName overrideAffinity -propertyValue true]')

    Note: Application Edition routing rules always override affinity if the affinity server is not among the permit destinations of the application edition rule.



 

Results

After the rules are defined, when a web server connects to the cell, the rules associated with that web server are delivered. The web server matches requests against the match expressions found in the rules. The expressions are evaluated according to the rule order, from lowest order to highest. The first rule with a matching expression is used. The action associated with the rule determines how the request is handled. If no rules are matched, the request is load balanced across all servers that can handle the request.

By default, when a request has session affinity, server selection is based on affinity. If an affinity server is found, that server is chosen and the routing rules are not evaluated. To allow routing rules to override affinity selection, set the overrideAffinity attribute of WebServerRoutingRules to true.

Note: Application Edition routing rules always override affinity if the affinity server is not among the permit destinations of the application edition rule.

 

Example

The following example shows the setup of multiple rules:

AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 -nodeName node1 -order 100 –expression “URI LIKE \’/AppX%\’” -actionType permit –routingLocations “cluster=cell1/clusterA&cluster=cell2/clusterA”]’) AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 -nodeName node1 -order 200 –expression “URI LIKE \’/myapp%\’” -actionType permit –routingLocations “server=cell1/*/*|server=cell2/*/*”]’) AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 -nodeName node1 -order 300 –expression “URI LIKE \’/AppY%\’ AND queryparm$test = \’true\’” -actionType permitMM –routingLocations “server=cell1/node1/server1”]’) AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 -nodeName node1 -order 400 –expression “URI LIKE \’/myoldapp%\’” -actionType redirect –redirectURL “http://mysite/mynewapp”]’) AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 -nodeName node1 -order 500 –expression “URI LIKE \’/myveryoldapp%\’” -actionType reject –errorCode 503]’)

The routing Rule with -order 100 limits the destinations where requests for /AppX are routed to two particular clusters across two cells.

The routing Rule with –order 200 shows how to enable failover from one set of endpoints to another. Rule 200 routes all requests that match the expression to any servers that can handle the request in cell1. If all servers that can handle the request in cell1 are unavailable, servers that can handle the request in cell2 are chosen for requests that match the rule expression.

The routing Rule with –order 300 shows an example of routing test requests to a server that is in maintenance mode. If “test=true” is added as a query parameter, then those requests will be sent to server1 in cell1, even if that server is in maintenance mode.

The routing Rule with –order 400 shows an example of a redirect rule.

The routing Rule with –order 500 shows an example of a reject rule.

 

Reference

The following describes the available AdminTasks for managing web server routing rules:

Detailed help for command group: WebServerRoutingRuleCommands

• Description: Administrative task commands to configure Web server routing rules.

  Commands:

  • addWebServerRoutingRule - Use this command to create a new routing rule.

    changeWebServerRoutingRuleAction - Use this command to change the action associated with an existing routing rule.

    changeWebServerRoutingRuleExpression - Use this command to change the expression associated with an existing routing rule.

    changeWebServerRoutingRuleOrder - Use this command to change the order associated with an existing routing rule.

    listWebServerRoutingRules - Use this command to list routing rules and their associated properties.

    removeWebServerRoutingRule - Use this command to remove an existing routing rule.

    setWebServerRoutingRulesProperty - Use this command to set properties associated with routing rules.

Detailed help for command: addWebServerRoutingRule

• Description: Use this command to create a new routing rule.
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.

    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

    *order - A positive integer value representing the order of the rule.

    *expression - A string value containing the match expression for the rule.

    *actionType - A string value containing the action to be executed when the rule expression is matched.

    Valid values are:

    permit: Permit routing to servers not in a maintenance mode.

    permitMM: Permit routing to servers even if in maintenance mode.

    redirect: Redirect the request to the URL specified by the redirectURL option.

    reject: Reject routing with return code specified by the errorcode option.

    routingLocations - This parameter is required if the actionType of the rule is permit or permitMM and is a string value containing a list of targets to which the request can be sent.

    Supported formats are:

    cluster=cellName/clusterName

    server=cellName/nodeName/serverName

    Multiple targets can be specified separated by an & (ampersand) to indicate a load balancing group and a | (vertical bar) to indicate fail-over groups.

    errorCode - This parameter is required if the actionType of the rule is reject and is an integer value containing the return code to be used when rejecting the request.

    redirectURL - This parameter is required if the actionType of the rule is redirect and is a string value containing the URL that the request will be redirected to.

Detailed help for command: changeWebServerRoutingRuleAction

• Description: Use this command to change the action associated with an existing routing rule.
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.

    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

    *order - A positive integer value representing the order of the rule.

    *actionType - A string value containing the action to be executed when the rule expression is matched.

    Valid values are:

    permit: Permit routing to servers not in a maintenance mode.

    permitMM: Permit routing to servers even if in maintenance mode.

    redirect: Redirect the request to the URL specified by the redirectURL option.

    reject: Reject routing with return code specified by the errorcode option.

    routingLocations - This parameter is required if the actionType of the rule is permit or permitMM and is a string value containing a list of targets to which the request can be sent.

    Supported formats are:

    cluster=cellName/clusterName

    server=cellName/nodeName/serverName

    Multiple targets can be specified separated by an & (ampersand) to indicate a load balancing group and a | (vertical bar) to indicate fail-over groups.

    errorCode - This parameter is required if the actionType of the rule is reject and is an integer value containing the return code to be used when rejecting the request.

    redirectURL - This parameter is required if the actionType of the rule is redirect and is a string value containing the URL that the request will be redirected to.

Detailed help for command: changeWebServerRoutingRuleExpression

• Description: Use this command to change the expression associated with
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.

    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

    *order - A positive integer value representing the order of the rule.

    *expression - A string value containing the match expression for the rule.

Detailed help for command: changeWebServerRoutingRuleOrder

• Description: Use this command to change the order associated with an existing routing rule.
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.

    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

    *order - A positive integer value representing the order of the rule.

    *newOrder - A positive integer value representing the new order of an existing routing rule.

Detailed help for command: listWebServerRoutingRules

• Description: Use this command to list routing rules and their associated properties.
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.

    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

Detailed help for command: removeWebServerRoutingRule

• Description: Use this command to remove an existing routing rule.
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.
    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

    *order - A positive integer value representing the order of the rule.

Detailed help for command: setWebServerRoutingRulesProperty

• Description: Use this command to set properties associated with routing rules.
  Arguments:
  • *nodeName - The name of the node hosting the web server or custom HTTP server that the routing rule applies to.

    *serverName - The name of the web server or custom HTTP server that the routing rule applies to.

    *propertyName - The name of the property to set. Currently the only valid property name is 'overrideAffinity'.

    *propertyValue - The value of the property to set. Currently the only valid property values are 'true' and 'false'.