Using WebSphere Service Registry and Repository V8 and DataPower V5 for service level mediation policy enforcement

Content

Introduction

IBM WebSphere Service Registry and Repository (hereafter called WSRR) is a system for storing, accessing, and managing service metadata that is used to selection, invocation, management, governance, and reuse of services in an SOA. In other words, it is where you store information about services residing in your systems or other organizations' systems that you already use, plan to use, or want to be aware of. For example, an application can check WSRR just before invoking a service in order to locate the service instance best satisfying its functional and performance requirements.

WSRR can also play a role in other stages of the SOA life cycle. It includes a registry that stores information about services, such as their interfaces, operations, and parameters, and a metadata repository that provides a robust, extensible framework to accommodate the diverse nature of service usage. WSRR also provides management and governance capabilities that help you to get the most business value from your SOA.

You can also use WSRR to author and store policy documents and policy attachments. You can then create policy documents, attach them to objects stored in WSRR, and have the policies enforced at runtime by a policy enforcement point (PEP), such a WebSphere DataPower. In summary, WSRR is an essential component of a successful SOA.

WebSphere DataPower Appliances (hereafter called DataPower) enable wirespeed XML transformation. DataPower V5 can subscribe to a service stored in WSRR and automatically enforce any policies attached to the service's objects.

This article focuses on the service-level mediation (SLM) policies, which let the user specify an expression, such as 500 messages per second, and what should happen when the expression is true or false. For example, when the expression is true, you might want to queue any subsequent messages until the expression is no longer true.

This new integration between WSRR and DataPower is a powerful tool to enforce service-level agreements (SLAs) and service-level definitions (SLDs). An SLD is a service provider's statement of what it offers and an SLA is an agreement between a service provider and a service consumer specifying what the consumer is allowed to consume. For example, if a service consumer is allowed to make no more than 400 requests per minute on Tuesdays, with their excess requests rejected, then you can create a policy that says that and attach it to the relevant SLA in WSRR to enforce it.

This article provides a set of sample objects and shows you how to import them into WSRR so that they make up all the governed objects in the correct state required for a policy to be attached. Then the article shows you how to create a web service proxy in DataPower that will be subscribed to the WSDL in WSRR and will therefore automatically enforce any policies attached to it. Finally the article shows you how to load an existing policy into WSRR and attach it so that it can be enforced by DataPower.

Requirements

• WSRR V8.0 (or later) with security enabled
• A WSRR configuration profile deployed and activated as the WSRR Governance Enablement Profile (GEP)
• WebSphere Business Space installed and configured to work with WSRR, and spaces based on each of the four WSRR templates
• WebSphere DataPower V5.0
• WSRR and DataPower configured to communicate securely, as explained in the developerWorks article Integrating WSRR V8 with DataPower V5: Secure connectivity and basic configuration.

You can download a sample web service at the bottom of this article. It is packaged as an EAR file and must be deployed into a WebSphere Application Server instance of your choice. Then you can access a web-based client for the web service at http://localhost:9080/jkhleClient/sampleEligibility_ServiceProxy/TestClient.jsp, where localhost:9080 is your actual host name and port number. This client lets you set all parameters needed to fully exercise this functionality and is described below.

Importing objects into WSRR

For the sake of simplicity, this article does not show you how to create the required objects in WSRR, but instead provides you with a .zip file to import. For more information on this topic, including how to create the objects yourself, see the GEP Tutorial in the WSRR information center.

If you're not following the GEP tutorial...

To import the zip file, navigate to the WSRR Web UI, typically, https://yourserver:9443/ServiceRegistry, and change to the Administrator perspective at the top right. Under Actions, select Import, click Browse, and navigate to where you have saved GeppedObjects.zip. Double-click it and then click OK. After a wait, you will be told that you have successfully imported one object, but you have really imported all the objects created in the GEP tutorial.

For everyone...

Whether you imported GeppedObjects.zip or followed the GEP tutorial yourself, you also need to import Policies.zip which contains the three policies used in this article: RouteToRealEndpoint, RejectAll, and Queueing policy. To do this, follow the procedure in the above paragraph for Policies.zip.

Creating a web service proxy

1. Navigate to the DataPower Control Panel for your domain, typically https://<hostname>:9090, and click the Web Service Proxy icon.
2. On the new page click Add, enter a name for your new proxy, such as EligibilityServiceWSP, and then click Create Web Service Proxy.
3. From the WSDL files tab, click Add WSRR Subscription and enter a name for the subscription, such as the name of the WSDL file you are subscribing to, which in this case is EligibilityService.wsdl.
4. Leave the Subscription Object as WSDL Document. Enter the Object Name and Namespace based on the WSDL, which for the eligibility service is EligibilityService.wsdl and http://jkhle.com/Eligibility_Service respectively.
5. For the WSRR server, select the server you created earlier from the drop-down menu.
6. Change the Synchronization method to Automatic (WSRR 7.5 or later) and then click Next:

   Creating the WSDL subscription

7. Create a Local Endpoint Handler. Click the + button in the left column and select HTTP Front Side Handler.
8. In the new window enter a name for the handler, such as EligibilityServiceFSH and an unused port number, and then click Apply, which will return you to the previous window:

   Creating an HTTP Front Side Handler

9. The newly created HTTP Front Side Handler will now be selected. Click Add in the far right column of the table and then click Next. Save the configuration:

   Configuring the web server proxy

Completing the governance and policy objects in WSRR

Earlier you imported three policies into WSRR: RouteToRealEndpoint, RejectAll, and Queueing policy. You will now create some new objects in the registry, govern them, and attach policies to objects new and old.

Anonymous SLA

A great feature of DataPower is its ability to enforce SLAs defined in WSRR. When a message comes into DataPower that doesn't have an associated SLA or simply doesn't identify itself, DataPower defers to the Anonymous SLA for that service. In the current example there is no Anonymous SLA as it is not included in the GEP Tutorial. The next step is to create one and attach the RejectAll policy to it to block service invocations from consumers without a valid SLA in place.

1. To create the Anonymous SLA, log in to the WSRR Business Space UI, typically https://yourserver:9443/BusinessSpace, and go to your Service Registry for Operations space.
2. On the Overview page in the Watch List, click SLD -- Eligibility service to open it in the Detail widget. Click the Pencil icon in the top right corner of the widget to edit the SLD.
3. Scroll to the bottom of the Edit window and under Anonymous SLA, click Add Service Level Agreement and then click Create.
4. In the Create window, enter Anonymous SLA -- Eligibility Service in the Name Property field.
5. Under Agreed Endpoints, click Add Service Level Definition.
6. In the newly displayed name field, begin entering SLD -- Eligibility service and select it once it is autosuggested.
7. To attach the policy, under Attached Policies, click Add Policy. As before, start entering RejectAll and select it.
8. Click Finish to create the Anonymous SLA, then click Finish again to save the SLD, which now points to the new Anonymous SLA:

   Creating the anonymous SLA

9. Your Anonymous SLA is now ready to use with its policy attached, but it is not yet in the correct governance state. In the Detail widget, scroll to the bottom and click Anonymous SLA -- Eligibility Service to display the details of your new Anonymous SLA. You can see that it is in the SLA Identified state.
10. Transition the SLA to the SLA Requested state: Click Action => Request SLA and then click OK.
11. Approve the SLA: Click Action => Approve SLA request and then click OK.
12. Activate the SLA: Click Action => Activate SLA and then click OK. The Governance State should now be SLA Active.

Editing the SLD

In order for DataPower to know which SLA to use for an incoming message, messages must contain a Consumer ID and a Context ID. The consumer ID is for a given consumer, such as a company, or perhaps a department for an internal service consumer. The context ID allows different messages from each consumer to get different levels of service depending on who or what is the consumer. For example, the Account creation service might have two SLAs for the Eligibility Service. One, for the Account Creation Service's premium customers and with a higher price, might guarantee an 0.5-second response time and up to 100 messages per second. A cheaper SLA for normal customers of the Account Creation Service might guarantee only a 5-second response time and up to 500 messages per second.

The SLD describes how a service should be used. It references, for a web service, the WSDL port and binding. It also has any policies which apply to the service for all consumers. For use with SLA enforcement, it is where the locations of the Consumer ID and Context ID are specified.

1. To set these locations, remain in the WSRR Business Space UI and the Operations space. From the Watch List navigate to your SLD (SLD - Eligibility service) and click the Pencil icon to edit.
2. Expand Additional Properties and paste in the values shown in the table and figure below:

Adding identifier location information

3. Click Finish to save the new property values. For more information on possible values for these locations, see Service level definition in the WSRR information center. The set of objects you loaded in from geppedObjects.zip (or created yourself by following the GEP Tutorial) included a WSDL with the endpoint URL of http://www.jkhle.com/jkhle/services/Eligibility. Clearly this is not the endpoint where you have deployed the sample EAR. In a real-world scenario, you would never have loaded the wrong WSDL, so instead of making you load the correct WSDL here and govern it, you will use a routing policy to make DataPower route to the real endpoint..
4. Imported from the Policies.zip file was a policy called RouteToRealEndpoint. It will do the routing but needs to be edited to add your URL. In the Search widget, select Policy Document in the drop-down, click Search, and then click RouteToRealEndpoint.xml to open the policy in the Detail widget.
5. Click the Pencil icon, and in the Edit panel that appears, modify the endpoint to use the host and HTTP port of the server where you have deployed the sample EAR file. Click Finish.
6. The policy is now finished, but is only in the Identified state. To work, it must be in the Approved state. Transition the policy to the Specification Review state: In the Detail widget, click Action => Propose Specification and then click OK.
7. Approve the Policy: click Action => Approve Specification. The policy is now in the Approved state and is ready to be attached to the SLD.
8. At the bottom of the Detail widget, click RouteToRealEndpointunder Policy Expressions. Then under Actions, click Manage Policy Attachments.
9. In the opened panel, click Attach to Specific Itemsand then start entering SLD -- Eligibility service in the Name box and select it when it is auto-suggested. The dialog should look like the figure below.

   Attaching a policy with the Manage Policy Attachment dialog

10. Click Finish to persist your changes.

Editing the SLA

You now need to edit the SLA that you imported from the .zip file, or created as part of the GEP tutorial, in order to add the Context Identifier and attach the Queueing Policy:

1. In the Watch List, click SLA -- Account creation consumption of eligibility service and then click the Pencil icon at the top right corner of the Detail widget.
2. Enter Gold as the value for the Context Identifier and then scroll down and under Attached Policies, click Add Policy.
3. Start entering Queueing Policy and select it when it is auto-suggested. Click Finish.
4. You are now finished modifying the objects in WSRR. DataPower has been receiving notifications of the changes you made, and five minutes after the last change, it updates the web service proxy, which you can see in the log of the default domain, as shown below. In order to see this log you must have access to the default domain and have a defined Event Subscription for your Log Target with an Event Category of wsrr and a Minimum Event Priority of debug. You can either wait the five minutes, or if you know how, you can manually perform a Synchronize to pick up the new policies.

   Logging the notification from WSRR in DataPower

Verifying your policies

An EAR file is supplied with this article with a version of the Eligibility service and a web client for that service. The web client lets you set the Context Identifier, Consumer Identifier, and Endpoint that is called, so that you can direct it to call the Eligibility service through the web service proxy you have created in DataPower and be subject to the policies that you have attached in WSRR.

1. Assuming that you have deployed EligibilityService.ear, as stated in the Requirements section above, navigate to the test client at http://<host>:<port>/jkhleClient/sampleEligibility_ServiceProxy/TestClient.jsp where host and port are the correct host and port for the server where you deployed the EAR file. The client is self-explanatory and comes with default values for all parameters.
2. You must change the endpoint value to point to the web service proxy that you created earlier in DataPower. Now you are ready to send messages.

   Web client for the Eligibility Service

3. With the default values you should see that messages are sent successfully (at least the first five in a minute). If you change the Context Identifier to Silver or Bronze, you will see that the messages are rejected, since there is no SLA in place and the Anonymous SLA has the RejectAll policy attached.

You can now use what you have learned to create your own SLAs and policies for Silver and Bronze. Remember that your SLAs must be Active and your policies Approved for them to be enforced.

Conclusion

In this article, you imported sample objects into WSRR and created a web service proxy in DataPower. You then subscribed to the WSDL stored in WSRR, which caused DataPower to automatically enforce the policies attached to the service. Then you loaded policies into WSRR and attached them at various points to be enforced by DataPower. The automatic subscription caused DataPower to enforce them without any further action.

This powerful functionality lets you use WSRR to author and attach policies to services directly from the WSRR Business Space UI, giving your business efficient and dynamic control over its services. In addition, the anonymous SLA lets you prevent unauthorized use of services or limit it to a greatly reduced level, so that it cannot impact service consumers with explicit agreements in place.