X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapex%2FAPEX-User-Manual.rst;h=75032466ee40180d99cfbccbadba9c6bbf007f8d;hb=508fe1a356d3f82dcb6f3de459c8949069cb0298;hp=1136034e3c7e8110468bc4299ba0200b36709f40;hpb=ebd9793f560311eda56deb0d98a6d9833a2de0ae;p=policy%2Fparent.git diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst index 1136034e..75032466 100644 --- a/docs/apex/APEX-User-Manual.rst +++ b/docs/apex/APEX-User-Manual.rst @@ -8,8 +8,8 @@ APEX User Manual .. contents:: :depth: 3 -Installation -^^^^^^^^^^^^ +Installation of Apex +^^^^^^^^^^^^^^^^^^^^ Requirements ------------ @@ -226,13 +226,14 @@ Build APEX +----------------------------------------------------------------------------------------------------------------+ | Unix, Cygwin | +================================================================================================================+ -| .. container:: | +| .. container:: content | | | | .. container:: listingblock | | | | .. container:: content | | | | .. code:: | +| | | :number-lines: | | | | -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* | @@ -1401,7 +1402,7 @@ Run in a docker container :number-lines: # docker run -p 6969:6969 -v $APEX_HOME/ToscaPolicy.json:/tmp/policy/ToscaPolicy.json \ - --name apex -it nexus3.onap.org:10001/onap/policy-apex-pdp:latest /bin/bash \ + --name apex -it nexus3.onap.org:10001/onap/policy-apex-pdp:latest \ -c "/opt/app/policy/apex-pdp/bin/apexEngine.sh -p /tmp/policy/ToscaPolicy.json" APEX Configurations Explained @@ -1556,8 +1557,7 @@ Engine Service Parameters "id" : 45, (3) "instanceCount" : 4, (4) "deploymentPort" : 12345, (5) - "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6a) - "policy_type_impl" : {...}, (6b) + "policy_type_impl" : {...}, (6) "periodicEventPeriod": 1000, (7) "engineParameters":{ (8) "executorParameters":{...}, (9) @@ -1599,13 +1599,7 @@ Engine Service Parameters | | Websocket connection to the | | | engine | +-----------------------------------+-----------------------------------+ - | **6a** | the APEX policy model file to | - | | load into the engine on startup | - | | when APEX is running native | - | | policies in standalone mode | - | | (optional) | - +-----------------------------------+-----------------------------------+ - | **6b** | the APEX policy model as a JSON | + | **6** | the APEX policy model as a JSON | | | or YAML block to load into the | | | engine on startup when | | | APEX is running a policy that has | @@ -1788,6 +1782,52 @@ Input and Output Interfaces | **18** | any other output configuration (e.g. event name filter, see below) | +--------+--------------------------------------------------------------------+ +Event Name +########## + + .. container:: paragraph + + Any event defined in APEX has to be unique. The "name" of + of an event is used as an identifier for an ApexEvent. Every + event has to be tagged to an eventName. This can be done in different + ways. Either the actual event can have a field called "name". Or, the + event has some other field that can act as the identifier, which can be + specified using "nameAlias". But in other cases, where a "name" or "nameAlias" + cannot be specified, the incoming event coming over an endpoint can be + manually tagged to an "eventName" before consuming it. + + .. container:: paragraph + + The "eventName" can have a single event's name if the event coming + over the endpoint has to be always mapped to the specified eventName's + definition. Otherwise, if different events can come over the endpoint, + then "eventName" field can consist of multiple event names separated by + "|" symbol. In this case, based on the received event's structure, it is + mapped to any one of the event name specified in the "eventName" field. + + .. container:: paragraph + + The following code shows some examples on how to specify the eventName field: + + .. container:: listingblock + + .. container:: content + + .. code:: + + "eventInputParameters": { + "Input1": { + "carrierTechnologyParameters" : {...}, + "eventProtocolParameters":{...}, + "eventName" : "VesEvent" (1) + }, + "Input2": { + "carrierTechnologyParameters" : {...}, + "eventProtocolParameters":{...}, + "eventName" : "AAISuccessResponseEvent|AAIFailureResponseEvent" (2) + } + } + Event Filters ############# @@ -2540,6 +2580,36 @@ Kafka Input "org.apache.kafka.common.serialization.StringDeserializer", (9) "valueDeserializer" : "org.apache.kafka.common.serialization.StringDeserializer" (10) + "kafkaProperties": [ (11) + [ + "security.protocol", + "SASL_SSL" + ], + [ + "ssl.truststore.type", + "JKS" + ], + [ + "ssl.truststore.location", + "/opt/app/policy/apex-pdp/etc/ssl/test.jks" + ], + [ + "ssl.truststore.password", + "policy0nap" + ], + [ + "sasl.mechanism", + "SCRAM-SHA-512" + ], + [ + "sasl.jaas.config", + "org.apache.kafka.common.security.scram.ScramLoginModule required username=\"policy\" password=\"policy\";" + ], + [ + "ssl.endpoint.identification.algorithm", + "" + ] + ] } } @@ -2566,6 +2636,13 @@ Kafka Input +--------+-------------------------------------+ | **10** | value for the Kafka de-serializer | +--------+-------------------------------------+ + | **11** | properties for Kafka connectivity | + +--------+-------------------------------------+ + + .. container:: paragraph + + Kindly note that the above Kafka properties is just a reference, + and the actual properties required depends on the Kafka server installation. Kafka Output ============ @@ -2598,32 +2675,69 @@ Kafka Output "org.apache.kafka.common.serialization.StringSerializer", (9) "valueSerializer" : "org.apache.kafka.common.serialization.StringSerializer" (10) + "kafkaProperties": [ (11) + [ + "security.protocol", + "SASL_SSL" + ], + [ + "ssl.truststore.type", + "JKS" + ], + [ + "ssl.truststore.location", + "/opt/app/policy/apex-pdp/etc/ssl/test.jks" + ], + [ + "ssl.truststore.password", + "policy0nap" + ], + [ + "sasl.mechanism", + "SCRAM-SHA-512" + ], + [ + "sasl.jaas.config", + "org.apache.kafka.common.security.scram.ScramLoginModule required username=\"policy\" password=\"policy\";" + ], + [ + "ssl.endpoint.identification.algorithm", + "" + ] + ] } } .. container:: colist arabic - +--------+---------------------------------+ - | **1** | set Kafka as carrier technology | - +--------+---------------------------------+ - | **2** | bootstrap server and port | - +--------+---------------------------------+ - | **3** | acknowledgement strategy | - +--------+---------------------------------+ - | **4** | number of retries | - +--------+---------------------------------+ - | **5** | batch size | - +--------+---------------------------------+ - | **6** | time to linger in milliseconds | - +--------+---------------------------------+ - | **7** | buffer memory in byte | - +--------+---------------------------------+ - | **8** | producer topic | - +--------+---------------------------------+ - | **9** | key for the Kafka serializer | - +--------+---------------------------------+ - | **10** | value for the Kafka serializer | - +--------+---------------------------------+ + +--------+-----------------------------------+ + | **1** | set Kafka as carrier technology | + +--------+-----------------------------------+ + | **2** | bootstrap server and port | + +--------+-----------------------------------+ + | **3** | acknowledgement strategy | + +--------+-----------------------------------+ + | **4** | number of retries | + +--------+-----------------------------------+ + | **5** | batch size | + +--------+-----------------------------------+ + | **6** | time to linger in milliseconds | + +--------+-----------------------------------+ + | **7** | buffer memory in byte | + +--------+-----------------------------------+ + | **8** | producer topic | + +--------+-----------------------------------+ + | **9** | key for the Kafka serializer | + +--------+-----------------------------------+ + | **10** | value for the Kafka serializer | + +--------+-----------------------------------+ + | **11** | properties for Kafka connectivity | + +--------+-----------------------------------+ + + .. container:: paragraph + + Kindly note that the above Kafka properties is just a reference, + and the actual properties required depends on the Kafka server installation. JMS IO ###### @@ -3836,7 +3950,6 @@ A configuration example "id" : 45, "instanceCount" : 4, "deploymentPort" : 12345, - "policyModelFileName" : "examples/models/some-model.json", "engineParameters" : { "executorParameters" : { "JAVASCRIPT" : { @@ -4055,12 +4168,9 @@ The APEX Engine .. container:: paragraph - The APEX engine comes with a few CLI arguments for setting - configuration and policy model. The configuration file is - always required. The policy model file is only required if - no model file is specified in the configuration, or if the - specified model file should be over written. The option - ``-h`` prints a help screen. + The APEX engine comes with a few CLI arguments, the main one is for setting + the tosca policy file for execution. The tosca policy file is + always required. The option ``-h`` prints a help screen. .. container:: listingblock @@ -4070,12 +4180,9 @@ The APEX Engine usage: org.onap.policy.apex.service.engine.main.ApexMain [options...] options - -c,--config-file the full path to the configuration file to use, the configuration file must be a Json file - containing the Apex configuration parameters - -h,--help outputs the usage of this command - -m,--model-file the full path to the model file to use, if set it overrides the model file set in the - configuration file - -v,--version outputs the version of Apex + -p,--tosca-policy-file the full path to the ToscaPolicy file to use. + -h,--help outputs the usage of this command + -v,--version outputs the version of Apex The APEX CLI Editor ------------------- @@ -5203,11 +5310,21 @@ Example Configuration for a Production Server +Unsupported Features +^^^^^^^^^^^^^^^^^^^^ + + .. container:: paragraph + + This section documents some legacy and unsupported features + in apex-pdp. The documentation here has not been updated for + recent versions of apex-pdp. For example, the apex-pdp models + specified in this example should now be in TOSCA format. + Building a System with Websocket Backend -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------- Websockets ----------- +########## .. container:: paragraph @@ -5229,7 +5346,7 @@ Websockets does not support WAMP at the moment. Websocket in Java ------------------ +################# .. container:: paragraph @@ -5243,7 +5360,7 @@ Websocket in Java Netty, … there are also Kafka extensions for Websockets. Websocket Example Code for Websocket clients (FOSS) ---------------------------------------------------- +################################################### .. container:: paragraph @@ -5276,7 +5393,7 @@ Websocket Example Code for Websocket clients (FOSS) example `__ BCP: Websocket Configuration ----------------------------- +############################ .. container:: paragraph @@ -5309,7 +5426,7 @@ BCP: Websocket Configuration reconnected manually after an APEX boot. Demo with VPN Policy Model --------------------------- +########################## .. container:: paragraph @@ -5336,7 +5453,7 @@ Demo with VPN Policy Model in an editor (we need to send those events to APEX) A Websocket Configuration for the VPN Domain -############################################ +******************************************** .. container:: paragraph @@ -5403,7 +5520,7 @@ A Websocket Configuration for the VPN Domain } Start APEX Engine -################# +***************** .. container:: paragraph @@ -5454,7 +5571,7 @@ Start APEX Engine policy is triggered/executed. Run the Websocket Echo Client -############################# +***************************** .. container:: paragraph @@ -5544,7 +5661,7 @@ Run the Websocket Echo Client ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake) Run the Websocket Console Client -################################ +******************************** .. container:: paragraph @@ -5635,7 +5752,7 @@ Run the Websocket Console Client ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake) Send Events -########### +*********** .. container:: paragraph @@ -5781,6 +5898,3 @@ Send Events .. container:: :name: footer-text - - -