Version 9
Created by objectiser on May 30, 2014 4:28 AM. Last modified by objectiser on Jul 17, 2014 10:55 AM.

    This document outlines the draft instructions for installing Overlord RTGov on Fuse 6.1. These instructions may change through the alpha/beta stage, and will be finalised in the RTGov documentation prior to the final release of version 2.0.0.

     

    Building from source

     

    RTGov includes some components that use Elasticsearch. These components have unit tests that expect an Elasticsearch server to be available at the default ports. If no such server is available, then use the -Pnoelasticsearch profile when building from source.

     

     

    Installing in Fuse 6.1

     

    Using the console

     

    Unpack Fuse 6.1 and unpack the attached configuration files into the etc folder. Then from the bin folder, launch fuse.

     

    When the console prompt is available, enter the following commands:

     

    1. features:addurl mvn:org.overlord.rtgov.karaf/rtgov-karaf-features/2.0.0-SNAPSHOT/xml/features
    2. features:install rtgov-all
    3. features:install rtgov-samples-ordermgmt-epn
    4. features:install rtgov-samples-sla
    5. features:install rtgov-samples-policy-sync
    6. features:install rtgov-samples-policy-async
    7. features:install rtgov-switchyard     (optionally depending on whether switchyard is installed)

     

    Step 2 installs what was previously known as the rtgov 'server' profile.

     

    Steps 3 and 4 install an example OSGi application that is monitored, with EPNs for converting exceptions into situations, checking for SLA violations. Steps 5 and 6 install example policies, one which is executed synchronously as part of the business transaction (a basic throttling example), and the other asynchronously, where the policy decision is taken outside the scope of the business transaction, but it's result can be used to block subsequent business transactions (e.g. credit limit expired causing the customers account to be suspended.

     

     

    As a profile in Fabric

     

    Unpack Fuse 6.1, unpack the overlord-rtgov-fabric-profiles.zip file (from the source build in release/karaf/profiles/target) and overlord-commons-profile.zip file (from the overlord-commons build in overlord-commons-dist/overlord-commons-dist-fuse6/target) into jboss-fuse-6.1.0.redhat-379/fabric/import/fabric/configs/versions/1.0/profiles and launch fuse from the bin folder.

     

    1. fabric:create --zookeeper-password admin      (you will be prompted to enter the username and password for an initial user - use 'admin' for both username and password)
    2. jaas:manage --index 3
    3. jaas:useradd karaf karaf
    4. jaas:roleadd karaf admin
    5. jaas:roleadd karaf overlorduser
    6. jaas:update
    7. fabric:container-create-child --jvm-opts '-Xms1000m -Xmx1000m' root child
      1. due to permgen and other (possible) memory issues, I also used '-Xms2048m -Xmx2048m -XX:PermSize=128m -XX:MaxPermSize=256m'
    8. fabric:container-add-profile child overlord-rtgov-all       (NOTE: Can also use the hawtio console to do this - see explanation below)
      1. also add the samples profile at the end of the command, e.g. overlord-rtgov-samples-all-ordermgmt overlord-rtgov-samples-all-sla

     

    It is also possible to perform steps 7 and 8 in one command:

         fabric:container-create-child --jvm-opts '-Xms2048m -Xmx2048m -XX:PermSize=128m -XX:MaxPermSize=256m' --profile overlord-rtgov-all root child

     

    Step 1 creates the fabric. Steps 2 to 6 setup the karaf user and its roles. Step 7 creates the child container in which the Overlord profiles will be installed.

     

    Step 8 - although this can be done from the command line console, using the http://localhost:8181/hawtio console enables you to see the stages the container goes through while adding the profile, and also to check the logs. Log into the UI using the admin/admin username and password. Simply select the Runtime tab, and the 'child' container - then add the profile by entering Overlord into the filter after pressing the +Add button. Then select the 'all', 'samples/all/ordermgmt and sla' checkboxes. Watch the "Provision Status" until it shows "success", and the "Server Status" is "Running".

     

     

    Trying the RTGov UI with samples

     

    To launch the UI, startup a browser and navigate to:

     

     

    The reason for the different port is that rtgov is installed in a separate container which runs on a different port. As it is the first additional container, it is associated with 8182 - but if further containers are created, this port number may be different.

     

    Login to the RTGov UI using the 'karaf' username and 'karaf' password.

     

    Select the Analytics button to launch the Kibana console in a separate tab. Then press the Situations button to navigate to the situation list.

     

    Using a REST client, send the following POST to the URL: http://localhost:8181/cxf/orderservice/orders/submit  (NOTE: Adjust the port number if running in a fabric container)

     

    {"orderId":"3","itemId":"JAM","quantity":100,"customer":"Fred"}

     

    This should create 2 situations, related to SLA violations.

     

    If you then POST the following message to the same URL,

     

    {"orderId":"6","itemId":"ERROR","quantity":100,"customer":"Fred"}

     

    You should see an exception reported in the situations list.

     

    If two order requests are submitted within 2 seconds of each other, the second request will be rejected. This is due to the 'policy-sync' example.

     

    If the customer 'Fred' becomes suspended (due to exceeding their credit limit being policed by the 'policy-async' example), then POST the following t the URL: http://localhost:8181/cxf/orderservice/orders/pay  (NOTE: Adjust the port number if running in a fabric container)

     

    {"amount":"400", "customer":"Fred"}

     

     

     

     

    Known Remaining Tasks and Issues

     

    • LoginService not found: https://issues.jboss.org/browse/RTGOV-476
      • intermittent problem - enabling debug appears to improve the situation, but requires further investigation
      • one possible temporary workaround is to add the profile when creating the child container, e.g.
        • fabric:container-create-child --jvm-opts '-Xms1000m -Xmx1000m' --profile overlord-rtgov-all root child      (along with any samples defined in additional --profile parameters)
      • even when console is not available due to this problem, if the samples have been deployed, they can be used, and view the situations using the following command direct to the Elasticsearch server:

     

    curl -XGET 'http://localhost:9700/rtgov/situation/_search?pretty=true' -d '
{
    "query" : {
        "matchAll" : {}
    }
}'
    615 Views Categories: Tags: