policy-based request routing and quality of service in ...€¦ · a routing policy work class...

Policy-based request routing and quality of servicein WebSphere Extended Deployment V6Skill Level: Intermediate

O. Michael Atogi ([email protected])WebSphere Extended Deployment DevelopmentIBM

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 XDcan either extract from the request URL, or from the request headers. Hence,WebSphere XD can classify each request using these rules, enabling enterprisesystem administrators to meet their business needs by configuring how WebSphereXD routes requests.

Introduction

WebSphere XD routes user requests to application servers running targetapplications. However, administrators might want to control which requests arerouted to which servers for various business reasons, including:

• Discriminating classes of users

• Directing buy requests to a secure server while directing inquiry requeststo 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

Policy-based request routing and quality of service in WebSphere Extended Deployment V6© Copyright IBM Corporation 1994, 2006. All rights reserved. of 18

mailto:[email protected]

http://www.ibm.com/legal/copytrade.shtml

XD policy-based request routing to control routing requests.

WebSphere XD versions 6.0 and later enable administrators to define rules-basedrouting and service policies. Routing policies control if and where a request isrouted. Service policies control how fast a request is serviced.

The rules determine the user or group discriminators, request types, requestsources, and request parameters. The policies dictate the action that WebSphereXD executes. The following sections cover the concepts of work classes, routing inWebSphere XD, routing policies, and rule expressions. Later sections show you howto apply this knowledge to direct client requests to particular servers and to re-directthese requests to different URLs.

What are work classes?

Policies are grouped into work classes, which are XML documents that encapsulatepolicy rules and applicable resources. When WebSphere XD processes a request,WebSphere XD evaluates the policies and takes the appropriate action. Eachprotocol has its own set of work classes for defining routing policies and servicepolicies. A routing policy work class exists on a per application basis, whereas aservice policy work class exists on a per-application edition basis.

The WebSphere XD on-demand router (ODR) is a proxy server with autonomicfunctionality that executes in its own JVM. To route a request to an application, theODR requires that the application have at least one work class for the request’scommunication protocol. Communication protocols in this context are HTTP andSOAP. WebSphere XD also uses work classes for other protocols such as IIOP andJMS requests, which the ODR does not route.

WebSphere XD creates default work classes during application deployment forenterprise applications. For system applications that are not deployed objects, theWebSphere XD profile augmentation automatically creates the default work classes.These default work classes base themselves on the protocol the deployedapplication or system application supports. For example, if the application has Webmodules and Web service modules, then WebSphere XD creates the default HTTPand SOAP work classes, as shown in Figure 1.

Figure 1. View from the Administration Console of the default work classes

developerWorks® ibm.com/developerWorks

Policy-based request routing and quality of service in WebSphere Extended Deployment V6 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.


Default work classes are very basic. The default routing match action for anapplication is to permit routing to the application for all URIs of the deployed webmodule. For a service policy, the default match action is the default transaction classof 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 routerequests to non-WebSphere application servers. These work classes have slightlydifferent naming convention than those of enterprise applications. The default GSCwork classes are named Default_<virtual_host_group>_<protocol >_WC. Thedefault work class name for a GSC, mapped to the virtual host group nameddefault_host, for an HTTP communication protocol, isDefault_default_host_HTTP_WC.

You can use work classes to do much more than simply accept the default rule anddefault match action of a policy type. The sections below show you how to modifythe default work classes or create new work classes, using either the adminconsole’s user interface, or the wsadmin scripts; and also discuss the rationale forbuilding complex classification rules.

About ODR routing

The ODR typically routes requests to application servers by employing two distinctprocessing steps:

ibm.com/developerWorks developerWorks®



1. Map request URI to an application.

2. If the mapping is successful, then ascertain the cluster and applicationserver or the standalone application server to route request to.

First, the ODR maps the request (virtual host - host name and port number - andrequest URI) to an internal configuration object, called an on-demand configurationnode or ODC node that represents the request URI. From the ODC URI node, theODR obtains the Web module and application respectively. The mapping of arequest URI to an application follows the Java Servlet Specification Version 2.4 thatrequires 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 pathprefix.

3. If that fails, then perform extension, for example, .jsp, match.

During configuration, the ODC creates the internal data mapping from an ODC URInode to a Web module URI pattern. This internal runtime configuration data stayscurrent through configuration change event listeners that respond to changes in therepository. Each configuration object is a node in the tree structure of ODC nodesbuilt from the WebSphere Application Server repository. An ODC node is a Javaobject with various attributes including those attributes that relate to other objects inthe same way that an XML element relates to other elements around it. So, if theODR cannot map a request URI to its corresponding ODC node, then furtherprocessing ceases and the usual HTTP status code of 404 (Not Found) returns tothe client browser.

If the ODR successfully maps the request to an ODC URI node, then from thatinitially mapped node, through object hierarchy and relationship the ODR canascertain both the cluster and the application server. Once the ODR finds theapplication server, the ODR can then find the appropriate transport endpoint andsend 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 respectto the protocol; the ODR routes incoming HTTP requests to application servers’HTTP transport endpoints, and routes incoming HTTPS requests to applicationservers’ HTTPS transport endpoints. However, if you configure the ODR to routeyour incoming HTTP requests to your application servers’ HTTPS transportendpoints, you can configure it by enabling SSL on load.




At this level of routing, there is very little user configuration that influences or altersthe routing process. The routing is very autonomic; the ODR discovers all thenecessary 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 policiesthrough 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 ruleswritten in the Message Selector Syntax of the Java Message Service (JMS 1.1). Youcan use routing policies to construct conditional expressions whose Boolean result isa routing action. You can use routing policies to define new application Web moduleURIs. WebSphere XD persists routing policies in the repository, in a workclass.xmlfile. 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="http://www.omg.org/XMI"

xmlns:workClass="http:///workClass.ecore" xmi:id="Default_HTTP_WC"matchAction="permit:DefaultApplication" name="Default_HTTP_WC">

<matchRules xmi:id="MatchRule_1157774978632"matchAction="redirect:http://w3.raleigh.ibm.com"matchExpression="clienthost like '%.raleigh.ibm.com'" priority="1" />

<workClassModules xmi:id="WorkClassModule_1154556296168"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 theworkclass.xml document. It has an attribute named matchAction. Thisattribute is used to define the routing action the ODR takes when no otherrules match for all URIs in the application Web module, indicated by thewildcard (*) in the workClassModules’s matchExpression attribute.When a user has not configured any rules, this is the only action that canbe performed as a result of evaluating the default work class.

• matchRules: this element is used to define routing rules. There can be




zero or more matchRules. When a user has not configured routing rulesfor an application, this element is absent. The matchRules element has 3attributes:

• priority

• matchExpression

• matchActionRules are ordered and processed by priority. The lowest number is thehighest priority and the highest number is the lowest priority. When youconfigure rules through the admin console, the rule priority monotonicallyincreases from the last rule number. If you configure rules using wsadminscripting, you specify the priority of each rule as part of the commandarguments. The matchExpression attribute holds the Boolean expressionthat you must construct using the syntax of Listing 2. The rule expressionin Listing 1 is the conditional expression:

matchExpression="clienthost like '%.raleigh.ibm.com'"

The expression states that if an incoming request originated from a hostin the domain that ends with raleigh.ibm.com, then take the action ofredirecting the request to http://w3.raleigh.ibm.com:

matchAction="redirect:http://w3.raleigh.ibm.com"

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 notmatch this rule follows the default action ofpermit:DefaultApplication in the root element, which says that theODR should route the request to the application server running theapplication named DefaultApplication..

• workClassModules: the element’s attribute, matchExpression, adds URImembers to the DefaultApplication web module, namedDefaultWebApplication.war.




Work classes for application routing policies are stored under theapplication in the following location in the repository:

cells/<cellName>/applications/<appEar>/workclasses/<workclassName>/workclass.xmlThe default work class name for the HTTP protocol is Default_HTTP_WC.Substituting the application name and work class name in the above pathyields:

cells/<cellName>/applications/DefaultApplication.ear/workclasses/Default_HTTP_WC/workclass.xmlWork classes for generic server clusters are located in the followinglocation in the repository:

cells/<cellName>/nodes/<nodeName>/<policy>/<odrName>/workclasses/<workclassName>/workclass.xmlwhere:

• <nodeName> is the name of the node

• <policy> is either routing or sla depending on whether the work classis 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 andthe HTTP protocol is:

cells/<cellName>/nodes/<nodeName>/routing/<odrName>/workclasses/Default_default_host_HTTP_WC/workclass.xml

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 theprotocols that the application supports. The ODR creates the default work class forthe protocol. But the system administrator can add rules to existing work classes orcreate new work classes. During request processing, the ODR evaluates all workclasses that the system administrator for that application and order the actionsbased on the priority of the rules. The ODR executes the rule with the highestpriority. In the event that no rule matched, the ODR executes the default action. Thesteps below describe the request processing sequence:

1. The ODR, at runtime, matches the incoming request URI to thecorresponding ODC node.

2. If the ODR finds a match, the ODR uses the match to derive the Webmodule and application. Because routing work classes are created at the




application level, once the ODR determines what the application is, theODR can obtain all of the application’s routing work classes, both thatcreated 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 thecorrect work class.

4. The ODR evaluates the routing rules at runtime by extracting the relevantdata from the request object, and passing that data to the rules engine toevaluate against rules in the corresponding work class.

5. The rules engine segregates the routing rules by work class, so that therules engine only evaluates the matched work class rules for theapplication against the request object.

6. If there is a match, the ODR queues the specified action, based on therule’s priority. Otherwise, the ODR takes the default action.

WebSphere XD obtains and evaluates the service policy work class for the incomingrequest in a similar manner. There are two differences between service policy workclasses and routing work classes:

• the origin of the work classes; the service policy work classes are storedon a per-application edition

• the matchAction

The matchAction for a service policy is a transaction class that maps to a serviceclass and determines the quality of service for the request. Each J2EE applicationhas at least the base edition. Service policy work classes have the following path:

cells/<callName>/applications/<appEar>/deployments/<appName>/workclasses/<workclassName>/workclass.xmlWebSphere XD processes the service policy work classes sequentially after therouting policy work classes. So, if there is a failure in routing policy work classprocessing, 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 ofrequests. You learned about rules in their elemental form, and where work classesare persisted in the repository. This section covers the syntax of the rules in theirconditional expression form. Listing 2 gives the general rule grammar using theBackus-Naur Form (BNF):

Listing 2. Rule syntax




<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 isan 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 Booleanresult. Expressions can be simple or complex, simple expressions use a singleoperator while complex expressions use the compound operators like AND, OR,NOT to combine simple expressions. Simple or complex, it is the result of evaluatingthe whole expression that determines its Boolean value. Operands arecase-sensitive while operators are case-insensitive.

Taxonomy of operands

The operands list is quite numerous, so how do you know which operands to use tocreate rules? Some of them might be discernable to an application developer, butnot to an administrator. For example, while the operands cookie$< name > andheader$< name > can be very powerful in using to prioritize requests, the rulecreator might not know what the < name > in any of those scopes might be andhence cannot use them in rule building. This section highlights a few of thewell-defined operands.

You can use the client-related operands: clienthost, clientipv4, clientipv6, andqueryparm$<name>, to easily create rules because you probably already havesome knowledge of what group of addresses or domain names to exclude from asensitive application, or to re-direct to a different URL, or to reject the requestcoming from suspicious client host or IP address. Such rules follow the form:

if ( clienthost LIKE ‘%sub-domain’) then routing_policywhere sub-domain could be, for example, .ibm.com, and routing_policy could bepermit:IBMerApp. So substituting those values into the rule, the rule looks like:




if ( clienthost LIKE ‘%.ibm.com’) then permit:IBMerApp

Administer work classes, routing rules, and routing policiesusing the Administration Console

Now that you know all about rules, routing policies, and work classes, you can learnhow to actually create work classes, and add rules and routing policies to existingwork classes. The work classes that you modify or create contain the rules thatenable certain requests to go to certain application servers using, for example, usingthe 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 therepository 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 workclasses for automation purposes.

Add rules and routing policies to an existing work class

This section shows you how to use the WebSphere Application ServerAdministration Console to work through the steps necessary to add rules and routingpolicies to an existing work class. This section uses the HTTP default work classnamed Default_HTTP_WC.

1. In the Administration console, select Applications->EnterpriseApplications-> <appName> ->Routing Policies, as in Figure 2.Figure 2. Routing Policies tab




2. Expand the Work Classes for HTTP Requests -> Default_HTTP_WC byclicking 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




4. Select Client Host from the Select Operand list, Like (like) from theOperator 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 theQuick Edit mode to add the rule and the action in a few clicks. Quick Edit is underthe Routing Rule column, as shown in Figure 6.

Figure 6. Quick Edit




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.




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 withQuick edit, you must know the operands, operators, and correct language syntax,whereas the Rule Builder guides you through every step and fills in the correctsyntax. 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 createthe 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 weare going to create a work class for the HTTP protocol. Under WorkClasses 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 theHTTP patterns for this Web module to the Members of<WorkClassName> list, as in Figure 7.

1. To assign an existing HTTP pattern to the Web module, select thepattern from Available HTTP patterns and click Add. ,

2. To assign a custom HTTP pattern to the Web module, enter thepattern you want to use into the Custom HTTP pattern field, andclick Add Pattern.

3. When you finish editing, click Next.Figure 7. Select the HTTP patterns for your Web module




5. Click Finish -> OK. Your new work class appears below the existingclass, as in Figure 8.

Figure 8. Creating a work class step 5

Generally, you can add rules and routing policies to existing work class, withouthaving to create a second work class. It is easier to understand the overall flow




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 beeasier 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 inapplication 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 buyoperation of the Stock WebService in the Management module of application A is asingle SOAP resource.

Each resource always associates with a single work class. In other words, when arequest 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 theassociated work class for the request. For example, suppose application A containsa work class named MyWorkClass with the pattern “/mypattern/*”. Each applicationcontains a default HTTP work class containing the pattern “ /*”. The associatedwork class for a request with URI “/mypattern/myservlet” is MyWorkClass, but theassociated work class for a request with URI “/otherpattern/myservlet” is the defaultwork class named Default_HTTP_WC.

So when should you create multiple work classes? If you want to apply differentpolicies to different resources within a single application, you should create multiplework classes. This enables you to modify the rules associated with one set ofresources 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 ofresources are almost identical and you want to avoid the overhead of managing twoseparate lists of rules, you might want to combine the resources into a single workclass, and use the HTTP uri operand, or the SOAP service or operationoperands, 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 yourWebSphere installation to administer work classes, add rules, add policies and muchmore. You can use workclassoperations.py to perform work class operations that




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 genericserver 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 aservice policy. Thus, to create a set of work classes for an enterprise application anda generic server cluster, you must execute workclassoperations.py at least twice.While this command requires some options, like -wctype and –wcname, for allinvocations, the command can require other options based on the combination ofoptions and the intended operation.

For examples and more information on workclassoperations.py, see “Managing workclasses with scripts” on the WebSphere XD Info Center athttp://publib.boulder.ibm.com/infocenter/wxdinfo/v6r0/index.jsp?topic=/com.ibm.websphere.xd.doc/info/odoe_task/rodwcscript.html.

Conclusion

This article explained how the ODR routes requests. Using user-defined routingpolicies, you can further customize the ODR to route requests traffic in a way thatbest suits your business goals and needs. This article also explained routing rulesand showed how you can build rules, either by using the Administration console userinterface, or by scripting. This article offered a rationale for creating multiple workclasses, versus adding rules and policy actions to an existing work class.



http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r0/index.jsp?topic=/com.ibm.websphere.xd.doc/info/odoe_task/rodwcscript.html


Resources

• K Brown, et al, Exploring new network topologies made possible by WebSphereXD and the On Demand Router,http://www.ibm.com/developerworks/websphere/techjournal/0509_brown/0509_brown.html

• Managing work classes with scripts,http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r0/index.jsp?topic=/com.ibm.websphere.xd.doc/info/odoe_task/rodwcscript.html

• Routing and service policies for work classes,http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r0/index.jsp?topic=/com.ibm.websphere.xd.doc/info/odoe_task/rodrworkclass.html

About the author

O. Michael AtogiO. Michael Atogi is a software developer at the IBM Raleigh Lab in Durham, NorthCarolina. He currently works on WebSphere XD development.



http://www.ibm.com/developerworks/websphere/techjournal/0509_brown/0509_brown.html

http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r0/index.jsp?topic=/com.ibm.websphere.xd.doc/info/odoe_task/rodwcscript.html

http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r0/index.jsp?topic=/com.ibm.websphere.xd.doc/info/odoe_task/rodrworkclass.html


policy-based request routing and quality of service in ...€¦ · a routing policy work class...

Documents