JBoss Community Archive (Read Only)

RHQ 4.9

Design-API

Purpose

To provide an initial set of remote services satisfying known or anticipated integration use cases.

Requirements

  • Authenticated Access
    Callers of the remote services must provide login information. The credentials must relate to a User already defined in the system and access/operations will be constrained given the granted permissions and roles for that user. The remote services will permit no more than what could similarly be accomplished by that user via the GUI.

  • Secure Access
    Communication between the remote client and the WS Endpoint can be configured to be encrypted (Secure SSL).

  • Single Port Access
    The remote services should not require multiple ports to be opened in the customer environment.

  • Client support

    • For remote Java clients we will supply artifacts to simplify and speed client development.

    • Non-Java client support through WSDL client generation.

  • Satisfy Initial Integration Goals
    The initial set of offered services will be guided based on satisfying the currently selected Use Cases.

Proposed Solution

The proposed solution is to provide a Web Service remote API based on JBossWS 3.0.4/JAX-WS. This will provide the ability to communicate in a secured way over a single port, typically the standard RHQ port of 7080 (unsecure) or 7443 (secure).

For Java clients we plan to also provide a Serialization based remoting solution, lighter weight than a WSDL based client.

All remote sessions must begin by calling a login service which, given proper credentials, will return a Subject that must be provided on each subsequent remote service call. A logout service call will typically end the session. Multiple sessions may run concurrently using the same credentials.

The Use Cases provide the guidance for the original remote services and new remote services

Use Cases

The use cases give a more detailed idea of what the API must offer. Based on the existing use cases following lists summarize the current requirements:

Goals Summary

  • Authenticated sessions

  • Authorized services

  • Export/Read-Only focus

  • Resource and Group Level services

  • Operational control (i.e. Operation execution)

  • Live/Current metric data

  • User management

  • Deployment

Goals Summary

  • Most Administration

    • Content

    • HA

    • Template

    • Role

  • Group Definition/Creation

    • Dyna-Group Calculation

  • Configuration update

  • Inventory import/add/uninventory/delete

Applicable to all use cases:

  • login/logout will start/end all service interaction

  • resources includes resource groups where applicable

Use Case #1 - JBossAS Activation

  1. find a JBossAS resource of interest

  2. start/stop/restart the JBossAS resource

Use Case #2 - Export Alerts

  1. find resource(s) of interest

  2. get Alert History

Use Case #3 - Configuration Management

  1. find resources or plugins of interest

  2. get the current configuration

  3. Update the configuration

Use case #4 - Export current (live) Numeric or Trait metric data

  1. find resources of interest

  2. get the current metric data

Use Case #5 - Export Event data

  1. find resources of interest

  2. get event history

Use case #6 - Support the CLI

The CLI should be able to leverage the remote API as a remote client. Use cases of the CLI are therefore also candidates for use cases of the remote API.

Use case #7 - User management / LDAP Integration

Priority: High

  1. check user existence

  2. add user

  3. optionally, perform password mgmt

  4. assign to existing roles
    or

  5. delete user
    or update user

Use case #8 - Deployment

Source: M. Dickson

  1. Support CLI-based or direct deployments of ear/war/jar/scripts

Additional (Joe's)automate the import / ignore process

always want to import all jboss-as
always want to ignore certain other servers that may be running
come up with that forumla, then script it as each new box is added
also, be able to rename according to some internal conventions to make identification easier wrt infrastructure
need to expose connection properties as well as query for machine traits

sla reporting
figure out the percentage downtime across the enterprise / each box / each server

flexible alert notifications
today we don't implement "send me emails once / hr containing all alerts that have triggered"
integration with EmailManagerBean

system activity
query all BLAH created in the last X timeframe, groupby user (also support arbitrary timeframes)
BLAH := op defs / alert def / plugin configuration changes / visible groups created

dynagroup enhancements
dynagroups may not support expression to create groups properly (name contains substr1 or substr2)
so resource search and get the dynagroups grouping functionality via scripts
cron the script so as to mimic dynagroup recalculation intervals

ldap integration
new ldap users become new JON users and have roles/perms automatically setup for them
when user leaves ldap, then automatically disable corresponding JON account
how to provide ldap query funcs - ldap plugin, exposed slsb, tell them to use 3rd party api?

scheduled patch rollout
automatically add all resources in some group to a channel
patch a single instance or multiple instances
aggregate the statuses of "group patch" rollout

complex alert actions
execute operation (with arguments) on some arbitrary resource, as a result of an alert
pass some contextual information from the alert into the operation
can we make this simple for alerting on different levels - resource, group, template?

geographic affinity
query agents and group them into affinity based on location, name, subnet, etc
which agents are NOT connected to their primary?
might be indication of network health or unexpected failover events
also, are any agents not reporting back? last heard from time is greater than X

script chaining
instead of having to copy/paste functionality between scripts, allow decomposition
each script does some elemental work, can chain them together during a user session
login script, action script, logout script

dynamic favorites
add to / remove from resource / group / chart favorites based on rules
perhaps machines with ISSUES become favorites so they can easily be identified/worked on by ops
ISSUES := currently down, alerting often, problem metrics

reporting
recently added resources, anything imported in the last day - counts by resource category, resource type, agent, etc
system metrics / min - group by server, group by agent
report hardware summary for each machine, easy to see whether collection frequency is too high given physical limitations

hot-spot metric scheduling
if metric-based alert is triggered, automatically increase frequency of collection for that metric
after a restart, collect metrics quickly until box is proven stable, then decrease collection interval

alert escalation
instead of using notification policy, programmatically send alert email to some user
if "issue" not resolved in X time, send to next user in the list
question - is there a way to integrate this list into the core without too much work?
do escalation policies require us to implement alert ack'ing? (acknowledgements)

follow-the-sun alerting
similar to alert escalation, except that different users are notified depending on what time it is
if alert occurs at 18:00 UCT, notify the US support team, if 10:00 UTC notify the EU support team

maintenance windows
temporarily disable alerts across resource or group according to known maintenance windowsh2. Remote Clients

If time permits we will provide a client library for remote Java clients. This would include the Java Remote interfaces as well as the Java classes involved in the Remote methods. For non-Java clients the clients will need to be generated from the WSDL. Developer-level instructions for building remote clients will be provided.

Notes

Subsystem View (co-development)

The new Subsystem View Search queries may need to be exposed via Remote. Use cases may be added for this.

JSON

A JSON interface is a secondary goal but development resources will not be put on this effort if it endangers the WS delivery. It is hoped that JSON interfaces may be easily generated off the WS definitions.

Issues (review input requested)

Number of Types/Classes exposed

How diligent should we be about minimizing the number of types exposed in client and therefore required for operation. Reducing the exposed types may reduce the power and flexibilty of the API but will simplify the clients and/or client generation.

  • parameters

    • Decision: Avoid exposing 3rd party types. Provide flexible signatures.

  • return types

    • Decision: Avoid exposing 3rd party types.

  • exceptions (perhaps a single Exception type, or just Exception, or no Throws clauses?)

    • Decision: Avoid exposing 3rd party types.

Any need for LookupUtil to be able to return the RemoteManagers?

  • e.g. LookupUtil.getSubjectManagerRemote();

    • Decision: Do not integrate remotes into the current LookupUtil but may provide a separate LookupUtilRemote to support remote Java clients.

How does this play with the need for non-WS remoting?

Will this be sufficient (lightweight enough, performant enough) for CLI support?

    • Decision: Provide Serialiation-based remoting for Java clients, based on ghinkle remoting solution, piggyback on 7080 port.

      Any other integration use cases needing non-WS remote API?

Simeon Pinder(Tasked with evaluating our existing efforts in Remoting, I wanted to capture the following thoughts as they applied to our external interface)

REMOTING: Webservice(XML Interface), CLI

Audience: To provide a consumable remoting interface for system admins and integrators who may want to

  1. batch many commands to manipulate JON servers and the content they're managing.

  2. read metric and/or alert information( or batches therof) for any one resource that JON is managing/monitoring.

  3. use/integrate the management capabilities of JON or it's managed resources into a larger integrated offering.

The Remoting landscape

the remoting audiences' needs can be largely served by exposing JON functionality or a subset of that same functionality over 'command line'(CLI) and XML/SOAP(Web Service) interfaces simultaneously. Successfully exposing these 'remoting' apis mean that integrating/administrative client requests can now come from any application and/or language that can put together valid XML or text requests.

CLI concerns

From experience, the application interface exposed over CLI tends to be more human readable and broken down into simpler command sets displayed as pages of text. Users expect and are comfortable with short commands that automate some task.

  • No additional toolkits are usually available or required to contruct requests or operations. Command sets are kept small enough as to make such toolkits superfluous. Anything that is not easily achievable or consumable by the commands available should be obtained through the JON web UI or potentially through the XML remoting interface.

SOAP/XML Interface concerns

The exposed operations here tend to be more api oriented, focusing on machine readable methods to expose the underlying object model developed for an application before remoting was even considered. The side effect here is that successfully consuming these interfaces has historically been very challenging for non trivial applications. In other words, using the exposed SOAP interface for a given application can mean a WSDL with thousands of operations and thousands of lines of xsd(verbose type definition) with very little context as to which order to call operations in. It's analagous to a large java class with multiple operations and types where you're only given the method names(which you hope were done well) to guide you to the proper usage of the code. As developers we typically have an IDE and the ability to walk through and introspect each operation and implementation as the ultimate guide to understanding correct operation.

Formal documentation about which operations and correct ordering can help alleviate the above problem to some extent but suffers from the following problems:

  1. traditional synch/stale issues where information is out of date with most implementation changes.

  2. the delivered documentation for any one application interface is now necessaily a combination of WSDL and some formal documentation medium. While the WSDL is the formal machine readable interface for the exposed application, it is also one of the most confusing parts of consuming a remoting inferface for developers and lay consumers alike. Most people who speak WSDL forget how unintuitive that description/interface is to actually consume or even understand.

Which toolkits

Due to WSDL consumption concerns just mentioned, the majority of consumers will leverage some toolkit to facilitate successful consumption. Unless the consumers are using a recent toolkit and annotation enhancements, the process is still quite painful. Modern languages like .Net and Java have already enhanced their languages to hide the implementaiton concerns/details of webservice consumption. It is important to note that the available webservice toolkits for integration/remoting for external consumers is heavily influenced by the current dependencies of the existing external application. In other words, if you're a java application it may be non-trivial to deploy an additional updated jdk to utilize webservice enhancements for interoperation. If you are a C or C++ based application you may be stuck with GSoap implentations that have not yet added annotation support or transparent proxying. An additional concern for webservice consumption is that while WSDL is the accepted standard for an XML api interface and that there is considerable tooling around WSDL consumption, much of that tooling is dated and may not have full support for all the generated XSD types and the accompanying WSDLs generated with updated tooling.

Modern Toolkits

easiest consumption/integration path
* .Net:
Early to add functional Webservice annotations to their language, much of the type generation and automatic proxying exists as libraries and standard components. Only concerns may be actual integration and xsd type integration on actual implementations.
* Java(1.5 and greater)
Another easy one as the tooling and annotations do all creation, type definition and serialization/deserialization in a standard way with almost no added effort. Our greatest concern is to expose valid WSDLs which we do easily. This is the most trivial case and needs no further discussion.

Older Toolkits

WSDL consumption is sufficiently painful as to warrant concerns.
Type generation and connection of proxies is still fairly manual.

  • GSoap

  • Axis*

  • Web languages(PHP,etc...)

The key takeaway here is that up to now, most applications have simply defined their remoting/integration points by throwing up a WSDL and treating the consumption of that WSDL as a trivial process left up to the customer. Without modern tooling, consuming a 500K wsdl can be non-trivial as there is a lot of stitching that usually needs to occur to get successful connections to work. I've seen 1.5Mb and greater wsdls with several hundred operations for many different objects in the same interface.
( End of Scope/Detailed discussion )

 Recommendation

After checking out the beans that we mean to expose(~ 10-15), the amount of operations is fairly small and continuing on this path to completion with the addition of the following documentation/tutorials showing:

  1. Primer on the general objects that we expose(Accounts,Content,etc..ref existing docs.. as we should assume familiarity with those concepts already.)

  2. How to initiate a successful connection

  3. How to initiate conversation with the existing major beans for functionality(Schedules, Alerts, Events, etc.)
    these integration/client steps with code snippets should make for a fairly functional webservice interface for most clients and tool kits.
    We should keep in mind when expanding the amount of beans and methods, the discussions above, as JAX-WS makes remoting a lot simpler than it ever has been and still simpler than is available for many integrators. While integration code may be a few lines of code in java, for consumers using GSoap or Axis* the integrations can become annoying if the exposed information increases dramatically. As it stands I did a quick test(GSoap) but the Wsdls do compile down to types as expected with simple types. We should watch what happens when we build more complicated types like Configuration to monitor how consumable we continue to be with external SOAP toolkits...as JAX-WS on client and server is a trivial case.

Three approaches

  1. (Recommended) Continue to flesh out existing MBeans defined:
    For many applications there is a single WSDL interface for all of the exposed information. We've decomposed the problem a little but a small amount of documentation should be able to clarify that distinction.

Nice: Each SLSB maps to a WSDL. Focuses the business operations for a very specific object. One massive WSDL with all the types, operations, etc.. would be a little less consumble and a bit more expensive hit with each "Service" call from the java clients.

We might want to consider renaming the exposed Service names on the beans to:

-> SubjectManager --> UserAccountManager

Future Investigation tasks(shelved due to time frame)

  1. Build WS-Management protocol handling into the jboss remoting options:

    1. Status: Not enough time available to give this it's due analysis.

Pro: Pushes a Resource orient approach to each external interface. Like REST except leverages the WS* standards for serialization.
Con: Does not enjoy much industry adoption as a raw(WS*) webservice standards.
Pro: Should be able to build WSDL wrapper for WS-Man implementations so that existing WS* tooling continues to work.

  1. Build QMF adapter and attach QMF servers?
    Status: Not enough time available to give this it's due analysis. I suspect that this will necessitate the need for an additional server and port, but I'ave also heard of QMF adapters for JBoss that already exist.
    Pros: Compresses payloads to binary format so should be faster throughput.
    Cons: No real concept of meta data for automatic consumption. Basically without the concept of a WSDL, each client will require a person to parse/learn and custom build client server content for successful integration.
    Con: No tooling around automatic metadata consumption.
    Con: Lacks industry standard adoption of WS*.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 08:02:18 UTC, last content change 2013-09-18 19:41:19 UTC.