Policy-based request routing and quality of service in WebSphere Extended Deployment V6

Transcription

1 Policy-based request routing and quality of service in WebSphere Extended Deployment V6 Skill Level: Intermediate O. Michael Atogi WebSphere Extended Deployment Development IBM 10 Jan 2007 Routing and quality of service work classes extend the autonomic routing of IBM WebSphere Extended Deployment V6 (hereafter referred to as "WebSphere XD") through the use of user defined rules. These rules use variables that WebSphere XD can either extract from the request URL, or from the request headers. Hence, WebSphere XD can classify each request using these rules, enabling enterprise system administrators to meet their business needs by configuring how WebSphere XD routes requests. Introduction WebSphere XD routes user requests to application servers running target applications. However, administrators might want to control which requests are routed to which servers for various business reasons, including: Discriminating classes of users Directing buy requests to a secure server while directing inquiry requests to a non-secure server Directing known clients requests to servers with fast response time Re-directing requests to other URLs Rejecting suspicious requests This article shows WebSphere XD system administrators how to use WebSphere Copyright IBM Corporation 1994, All rights reserved. Page 1 of 18

2 developerworks ibm.com/developerworks XD policy-based request routing to control routing requests. WebSphere XD versions 6.0 and later enable administrators to define rules-based routing and service policies. Routing policies control if and where a request is routed. Service policies control how fast a request is serviced. The rules determine the user or group discriminators, request types, request sources, and request parameters. The policies dictate the action that WebSphere XD executes. The following sections cover the concepts of work classes, routing in WebSphere XD, routing policies, and rule expressions. Later sections show you how to apply this knowledge to direct client requests to particular servers and to re-direct these requests to different URLs. What are work classes? Policies are grouped into work classes, which are XML documents that encapsulate policy rules and applicable resources. When WebSphere XD processes a request, WebSphere XD evaluates the policies and takes the appropriate action. Each protocol has its own set of work classes for defining routing policies and service policies. A routing policy work class exists on a per application basis, whereas a service policy work class exists on a per-application edition basis. The WebSphere XD on-demand router (ODR) is a proxy server with autonomic functionality that executes in its own JVM. To route a request to an application, the ODR requires that the application have at least one work class for the request s communication protocol. Communication protocols in this context are HTTP and SOAP. WebSphere XD also uses work classes for other protocols such as IIOP and JMS requests, which the ODR does not route. WebSphere XD creates default work classes during application deployment for enterprise applications. For system applications that are not deployed objects, the WebSphere XD profile augmentation automatically creates the default work classes. These default work classes base themselves on the protocol the deployed application or system application supports. For example, if the application has Web modules and Web service modules, then WebSphere XD creates the default HTTP and SOAP work classes, as shown in Figure 1. Figure 1. View from the Administration Console of the default work classes Page 2 of 18 Copyright IBM Corporation 1994, All rights reserved.

3 ibm.com/developerworks developerworks Default work classes are very basic. The default routing match action for an application is to permit routing to the application for all URIs of the deployed web module. For a service policy, the default match action is the default transaction class of the default service policy. WebSphere XD also creates default work classes for generic server clusters (GSC). A GSC is a collection of one or more endpoints that WebSphere XD uses to route requests to non-websphere application servers. These work classes have slightly different naming convention than those of enterprise applications. The default GSC work classes are named Default_<virtual_host_group>_<protocol >_WC. The default work class name for a GSC, mapped to the virtual host group named default_host, for an HTTP communication protocol, is Default_default_host_HTTP_WC. You can use work classes to do much more than simply accept the default rule and default match action of a policy type. The sections below show you how to modify the default work classes or create new work classes, using either the admin console s user interface, or the wsadmin scripts; and also discuss the rationale for building complex classification rules. About ODR routing The ODR typically routes requests to application servers by employing two distinct processing steps: Copyright IBM Corporation 1994, All rights reserved. Page 3 of 18

4 developerworks ibm.com/developerworks 1. Map request URI to an application. 2. If the mapping is successful, then ascertain the cluster and application server or the standalone application server to route request to. First, the ODR maps the request (virtual host - host name and port number - and request URI) to an internal configuration object, called an on-demand configuration node or ODC node that represents the request URI. From the ODC URI node, the ODR obtains the Web module and application respectively. The mapping of a request URI to an application follows the Java Servlet Specification Version 2.4 that requires the ODR to perform the matching in the following order: 1. Perform an exact match 2. If that is not successful, then recursively try to match the longest path prefix. 3. If that fails, then perform extension, for example,.jsp, match. During configuration, the ODC creates the internal data mapping from an ODC URI node to a Web module URI pattern. This internal runtime configuration data stays current through configuration change event listeners that respond to changes in the repository. Each configuration object is a node in the tree structure of ODC nodes built from the WebSphere Application Server repository. An ODC node is a Java object with various attributes including those attributes that relate to other objects in the same way that an XML element relates to other elements around it. So, if the ODR cannot map a request URI to its corresponding ODC node, then further processing ceases and the usual HTTP status code of 404 (Not Found) returns to the client browser. If the ODR successfully maps the request to an ODC URI node, then from that initially mapped node, through object hierarchy and relationship the ODR can ascertain both the cluster and the application server. Once the ODR finds the application server, the ODR can then find the appropriate transport endpoint and send the request. If the server is not available, then the HTTP status code of 503, Service Unavailable, returns. Request routing, by default, is symmetric with respect to the protocol; the ODR routes incoming HTTP requests to application servers HTTP transport endpoints, and routes incoming HTTPS requests to application servers HTTPS transport endpoints. However, if you configure the ODR to route your incoming HTTP requests to your application servers HTTPS transport endpoints, you can configure it by enabling SSL on load. Page 4 of 18 Copyright IBM Corporation 1994, All rights reserved.

5 ibm.com/developerworks developerworks At this level of routing, there is very little user configuration that influences or alters the routing process. The routing is very autonomic; the ODR discovers all the necessary configuration data through the ODC and performs request routing. Realize that in this mode, the application developer defined the entire request URIs, so you cannot alter the routing decision at application deployment. What are routing policies? This section shows you what a routing policy is, and how to create routing policies through the use of routing rules, routing actions, and work classes. Syntax of routing policies WebSphere XD V6.0.1 introduced routing policies. A routing policy is a set of rules written in the Message Selector Syntax of the Java Message Service (JMS 1.1). You can use routing policies to construct conditional expressions whose Boolean result is a routing action. You can use routing policies to define new application Web module URIs. WebSphere XD persists routing policies in the repository, in a workclass.xml file. Listing 1 below shows a workclass.xml file with one defined rule: Listing 1. workclass.xml <?xml version="1.0" encoding="utf-8"?> <workclass:workclass xmi:version="2.0" xmlns:xmi=" xmlns:workclass=" xmi:id="default_http_wc" matchaction="permit:defaultapplication" name="default_http_wc"> <matchrules xmi:id="matchrule_ " matchaction="redirect: matchexpression="clienthost like '%.raleigh.ibm.com'" priority="1" /> <workclassmodules xmi:id="workclassmodule_ " modulename="defaultwebapplication.war" matchexpression="*" id="default_http_wc:!:defaultapplication:!:defaultwebapplication.war" /> </workclass:workclass> A workclass.xml has three elements that are relevant to routing policies. These are: workclass:workclass: this element is the root element of the workclass.xml document. It has an attribute named matchaction. This attribute is used to define the routing action the ODR takes when no other rules match for all URIs in the application Web module, indicated by the wildcard (*) in the workclassmodules s matchexpression attribute. When a user has not configured any rules, this is the only action that can be performed as a result of evaluating the default work class. matchrules: this element is used to define routing rules. There can be Copyright IBM Corporation 1994, All rights reserved. Page 5 of 18

6 developerworks ibm.com/developerworks zero or more matchrules. When a user has not configured routing rules for an application, this element is absent. The matchrules element has 3 attributes: priority matchexpression matchaction Rules are ordered and processed by priority. The lowest number is the highest priority and the highest number is the lowest priority. When you configure rules through the admin console, the rule priority monotonically increases from the last rule number. If you configure rules using wsadmin scripting, you specify the priority of each rule as part of the command arguments. The matchexpression attribute holds the Boolean expression that you must construct using the syntax of Listing 2. The rule expression in Listing 1 is the conditional expression: matchexpression="clienthost like '%.raleigh.ibm.com'" The expression states that if an incoming request originated from a host in the domain that ends with raleigh.ibm.com, then take the action of redirecting the request to matchaction="redirect: There are four match actions that you can specify for a routing policy. These are: permit:<applicationname> permitsticky:<applicationname> reject:<http_error_code> redirect:<url> Any request to the J2EE application DefaultApplication that does not match this rule follows the default action of permit:defaultapplication in the root element, which says that the ODR should route the request to the application server running the application named DefaultApplication.. workclassmodules: the element s attribute, matchexpression, adds URI members to the DefaultApplication web module, named DefaultWebApplication.war. Page 6 of 18 Copyright IBM Corporation 1994, All rights reserved.

7 ibm.com/developerworks developerworks Work classes for application routing policies are stored under the application in the following location in the repository: cells/<cellname>/applications/<appear>/workclasses/<workclassname>/ The default work class name for the HTTP protocol is Default_HTTP_WC. Substituting the application name and work class name in the above path yields: cells/<cellname>/applications/defaultapplication.ear/workclasses/de Work classes for generic server clusters are located in the following location in the repository: cells/<cellname>/nodes/<nodename>/<policy>/<odrname>/workclasses/<w where: <nodename> is the name of the node <policy> is either routing or sla depending on whether the work class is for routing or service policy respectively <odrname> is the name of the ODR server <workclassname> is the name of the work class. The default work class name for virtual host group of default_host and the HTTP protocol is: cells/<cellname>/nodes/<nodename>/routing/<odrname>/workclasses/def How does the ODR use the work classes in prioritizing routing? The ODR routes to applications that have one or more work classes defined for the protocols that the application supports. The ODR creates the default work class for the protocol. But the system administrator can add rules to existing work classes or create new work classes. During request processing, the ODR evaluates all work classes that the system administrator for that application and order the actions based on the priority of the rules. The ODR executes the rule with the highest priority. In the event that no rule matched, the ODR executes the default action. The steps below describe the request processing sequence: 1. The ODR, at runtime, matches the incoming request URI to the corresponding ODC node. 2. If the ODR finds a match, the ODR uses the match to derive the Web module and application. Because routing work classes are created at the Copyright IBM Corporation 1994, All rights reserved. Page 7 of 18

8 developerworks ibm.com/developerworks application level, once the ODR determines what the application is, the ODR can obtain all of the application s routing work classes, both that created by the ODR and those that the user would have added as well. 3. The ODR matches the URI patterns to the Web module to obtain the correct work class. 4. The ODR evaluates the routing rules at runtime by extracting the relevant data from the request object, and passing that data to the rules engine to evaluate against rules in the corresponding work class. 5. The rules engine segregates the routing rules by work class, so that the rules engine only evaluates the matched work class rules for the application against the request object. 6. If there is a match, the ODR queues the specified action, based on the rule s priority. Otherwise, the ODR takes the default action. WebSphere XD obtains and evaluates the service policy work class for the incoming request in a similar manner. There are two differences between service policy work classes and routing work classes: the origin of the work classes; the service policy work classes are stored on a per-application edition the matchaction The matchaction for a service policy is a transaction class that maps to a service class and determines the quality of service for the request. Each J2EE application has at least the base edition. Service policy work classes have the following path: cells/<callname>/applications/<appear>/deployments/<appname>/workclasses/<w WebSphere XD processes the service policy work classes sequentially after the routing policy work classes. So, if there is a failure in routing policy work class processing, WebSphere XD does not process the service policy work classes. Syntax of routing rules In the previous sections, you learned about the rules for prioritizing the routing of requests. You learned about rules in their elemental form, and where work classes are persisted in the repository. This section covers the syntax of the rules in their conditional expression form. Listing 2 gives the general rule grammar using the Backus-Naur Form (BNF): Listing 2. Rule syntax Page 8 of 18 Copyright IBM Corporation 1994, All rights reserved.

9 ibm.com/developerworks developerworks <expression> ::= <operand> <operator> {<literalexpression>} [compoundoperator] {(<expression>)} <operand> ::= clienthost clientipv4 clientipv6 serverhost serveripv4 serveripv6 port MIMEType <operator> ::= <comparisonoperator> <existenceoperator> <comparisonoperator> ::= <> < <= > >= = LIKE BETWEEN <existenceoperator> ::= IN IS NOT NULL IS NULL <compoundoperator> ::= OR AND NOT <literalexpression> ::= <String> <number> <number> ::= [ 0-9 ]* <String> ::= single-quoted-string For example: clienthost like '%.raleigh.ibm.com clienthost is the variable, and in this article, operand is a synonym for variable; like is an operator; and the literal expression is enclosed in single quotes. The percent sign (%) is the wildcard character in JMS 1.1. Evaluation of expression yields a Boolean result. Expressions can be simple or complex, simple expressions use a single operator while complex expressions use the compound operators like AND, OR, NOT to combine simple expressions. Simple or complex, it is the result of evaluating the whole expression that determines its Boolean value. Operands are case-sensitive while operators are case-insensitive. Taxonomy of operands The operands list is quite numerous, so how do you know which operands to use to create rules? Some of them might be discernable to an application developer, but not to an administrator. For example, while the operands cookie$< name > and header$< name > can be very powerful in using to prioritize requests, the rule creator might not know what the < name > in any of those scopes might be and hence cannot use them in rule building. This section highlights a few of the well-defined operands. You can use the client-related operands: clienthost, clientipv4, clientipv6, and queryparm$<name>, to easily create rules because you probably already have some knowledge of what group of addresses or domain names to exclude from a sensitive application, or to re-direct to a different URL, or to reject the request coming from suspicious client host or IP address. Such rules follow the form: if ( clienthost LIKE %sub-domain ) then routing_policy where sub-domain could be, for example,.ibm.com, and routing_policy could be permit:ibmerapp. So substituting those values into the rule, the rule looks like: Copyright IBM Corporation 1994, All rights reserved. Page 9 of 18

10 developerworks ibm.com/developerworks if ( clienthost LIKE %.ibm.com ) then permit:ibmerapp Administer work classes, routing rules, and routing policies using the Administration Console Now that you know all about rules, routing policies, and work classes, you can learn how to actually create work classes, and add rules and routing policies to existing work classes. The work classes that you modify or create contain the rules that enable certain requests to go to certain application servers using, for example, using the clienthost operand in the rule, or re-directing certain requests to different URLs. The modified work class or newly created work class will be persisted in the repository location stated in the What are routing policies? section above. This section shows you how to administer work classes using the admin console. The next section shows you how you can use wsadmin scripts to administer work classes for automation purposes. Add rules and routing policies to an existing work class This section shows you how to use the WebSphere Application Server Administration Console to work through the steps necessary to add rules and routing policies to an existing work class. This section uses the HTTP default work class named Default_HTTP_WC. 1. In the Administration console, select Applications->Enterprise Applications-> <appname> ->Routing Policies, as in Figure 2. Figure 2. Routing Policies tab Page 10 of 18 Copyright IBM Corporation 1994, All rights reserved.

11 ibm.com/developerworks developerworks 2. Expand the Work Classes for HTTP Requests -> Default_HTTP_WC by clicking on the + sign, as in Figure 3. Figure 3. Expanded Work Classes for HTTP Requests section 3. Click Add Rule to open the Rule Builder, seen in Figure 4. Figure 4. The Rule Builder Copyright IBM Corporation 1994, All rights reserved. Page 11 of 18

12 developerworks ibm.com/developerworks 4. Select Client Host from the Select Operand list, Like (like) from the Operator list, enter in the URI pattern in the Value field, as in Figure 5. When you are done, click OK. Figure 5. Settings for the Rule Builder 5. Select Permit routing to from the Select action list, and click OK. You have completed adding a rule using the Rule Builder. You can also use the Quick Edit mode to add the rule and the action in a few clicks. Quick Edit is under the Routing Rule column, as shown in Figure 6. Figure 6. Quick Edit Page 12 of 18 Copyright IBM Corporation 1994, All rights reserved.

13 ibm.com/developerworks developerworks To create a rule in Quick Edit: 1. In the Quick Edit mode, type in your expression in the field below the If: clienthost = myhost.raleigh.ibm.com 2. To the right of Then, select Reject routing with return code. 3. In the Enter in return code field, enter 404 and click Apply. Copyright IBM Corporation 1994, All rights reserved. Page 13 of 18

14 developerworks ibm.com/developerworks 4. Click Save and follow the rest of the screens to save the configuration. The major difference between using Quick Edit and the Rule Builder is that with Quick edit, you must know the operands, operators, and correct language syntax, whereas the Rule Builder guides you through every step and fills in the correct syntax. So, use Quick Edit once you are familiar with the language and the syntax. Create a new work class This section describes the procedure for creating a new work class. After you create the work class, you can follow the above procedure to add routing rules and actions. 1. This first step assumes that you have navigated to Figure 3 above and we are going to create a work class for the HTTP protocol. Under Work Classes for HTTP Requests, click New. 2. Enter a work class name, like Test_WC, in the Name field and click Next. 3. Select the appropriate Web module from the Module list, and add the HTTP patterns for this Web module to the Members of <WorkClassName> list, as in Figure To assign an existing HTTP pattern to the Web module, select the pattern from Available HTTP patterns and click Add., 2. To assign a custom HTTP pattern to the Web module, enter the pattern you want to use into the Custom HTTP pattern field, and click Add Pattern. 3. When you finish editing, click Next. Figure 7. Select the HTTP patterns for your Web module Page 14 of 18 Copyright IBM Corporation 1994, All rights reserved.

15 ibm.com/developerworks developerworks 5. Click Finish -> OK. Your new work class appears below the existing class, as in Figure 8. Figure 8. Creating a work class step 5 Generally, you can add rules and routing policies to existing work class, without having to create a second work class. It is easier to understand the overall flow Copyright IBM Corporation 1994, All rights reserved. Page 15 of 18

16 developerworks ibm.com/developerworks when reading from only one work class, than when there are multiple work classes. For example, if your routing policy goal is to route all requests to a given application, except when the request is coming from a particular address or domain, it would be easier to just add that one conditional in the default work class for that protocol. However, there might be a case when a new work class is desirable. Single or multiple work classes? For HTTP, a group of resources within an application is identified as a collection of {Web module, URI pattern} 2-tuples. For example, the resources of module WM1 in application A might have two sets of URI patterns: /a/* and /b/*. For SOAP, a group of resources is identified as a collection of {module,webservice,webserviceoperation} 3-tuples. For example, the buy operation of the Stock WebService in the Management module of application A is a single SOAP resource. Each resource always associates with a single work class. In other words, when a request arrives at the ODR, the ODR first maps the request to a single work class. For HTTP, the work class with the most specific matching URI pattern is the associated work class for the request. For example, suppose application A contains a work class named MyWorkClass with the pattern /mypattern/*. Each application contains a default HTTP work class containing the pattern /*. The associated work class for a request with URI /mypattern/myservlet is MyWorkClass, but the associated work class for a request with URI /otherpattern/myservlet is the default work class named Default_HTTP_WC. So when should you create multiple work classes? If you want to apply different policies to different resources within a single application, you should create multiple work classes. This enables you to modify the rules associated with one set of resources while not affecting the rules associated with a different set of resources. There is one exception to this general rule: if the rules associated with two sets of resources are almost identical and you want to avoid the overhead of managing two separate lists of rules, you might want to combine the resources into a single work class, and use the HTTP uri operand, or the SOAP service or operation operands, to associate different policies with the different resources. Administer work classes using scripts You can use the Jython script workclassoperations.py in the bin directory of your WebSphere installation to administer work classes, add rules, add policies and much more. You can use workclassoperations.py to perform work class operations that Page 16 of 18 Copyright IBM Corporation 1994, All rights reserved.

17 ibm.com/developerworks developerworks you would otherwise perform through the administration console user interface. Description of workclassoperations.py The command workclassoperations.py can perform the following operations: Create or update work classes for a deployed application and/or generic server cluster List rules in a work class Get the default action defined in a work class Delete a rule in a work class Assign a URI to a work class Web module Modify URIs List URIs Remove work classes Each invocation can only create one work class; either for a routing policy, or for a service policy. Thus, to create a set of work classes for an enterprise application and a generic server cluster, you must execute workclassoperations.py at least twice. While this command requires some options, like -wctype and wcname, for all invocations, the command can require other options based on the combination of options and the intended operation. For examples and more information on workclassoperations.py, see Managing work classes with scripts on the WebSphere XD Info Center at Conclusion This article explained how the ODR routes requests. Using user-defined routing policies, you can further customize the ODR to route requests traffic in a way that best suits your business goals and needs. This article also explained routing rules and showed how you can build rules, either by using the Administration console user interface, or by scripting. This article offered a rationale for creating multiple work classes, versus adding rules and policy actions to an existing work class. Copyright IBM Corporation 1994, All rights reserved. Page 17 of 18

18 developerworks ibm.com/developerworks Resources K Brown, et al, Exploring new network topologies made possible by WebSphere XD and the On Demand Router, Managing work classes with scripts, Routing and service policies for work classes, About the author O. Michael Atogi O. Michael Atogi is a software developer at the IBM Raleigh Lab in Durham, North Carolina. He currently works on WebSphere XD development. Page 18 of 18 Copyright IBM Corporation 1994, All rights reserved.