| :number-lines: | :number-lines: |
| | |
| # cd /usr/local/src/apex-pdp | >c: |
- | # mvn clean install -DskipTest | >cd \dev\apex |
- | | >mvn clean install -DskipTests |
+ | # mvn clean install -Pdocker -DskipTests | >cd \dev\apex |
+ | | >mvn clean install -Pdocker -DskipTests |
+-------------------------------------------------------+--------------------------------------------------------+
.. container:: paragraph
| .. code:: |
| :number-lines: |
| |
-| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
+| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
| Selecting previously unselected package apex-uservice. |
| (Reading database ... 288458 files and directories currently installed.) |
| Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ... |
| :number-lines: | :number-lines: |
| | |
| # cd /usr/local/src/apex | >c: |
- | # mvn clean install -DskipTests | >cd \dev\apex |
- | | >mvn clean install -DskipTests |
+ | # mvn clean install -Pdocker -DskipTests | >cd \dev\apex |
+ | | >mvn clean install -Pdocker -DskipTests |
+-------------------------------------------------------+--------------------------------------------------------+
.. container:: paragraph
.. container:: paragraph
- ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />``
+ ``<property name="logDir" value="/var/log/onap/policy/apex-pdp/" />``
.. container:: paragraph
.. container:: paragraph
- ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />``
+ ``<property name="logDir" value="/PATH/TO/LOG/DIRECTORY/" />``
.. container:: paragraph
.. container:: paragraph
- ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``
+ ``<property name="logDir" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``
.. container:: paragraph
APEX was installed manually or when the log directory was changed
in the settings (see above).
- +------------------------------------------------------------------+-------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +==================================================================+=======================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | :number-lines: | :number-lines: |
- | | |
- | mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs |
- | chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | |
- +------------------------------------------------------------------+-------------------------------------------------------+
+ +-----------------------------------------------------------------------+-------------------------------------------------------+
+ | Unix, Cygwin | Windows |
+ +=======================================================================+=======================================================+
+ | .. container:: | .. container:: |
+ | | |
+ | .. container:: content | .. container:: content |
+ | | |
+ | .. code:: | .. code:: |
+ | :number-lines: | :number-lines: |
+ | | |
+ | sudo mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs |
+ | sudo chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | |
+ +-----------------------------------------------------------------------+-------------------------------------------------------+
Verify the APEX Installation
----------------------------
Unix scripts but runs Java as a Windows application, thus the
configuration file must be given as a Windows path.
+ .. container:: paragraph
+
+ On Unix/Linux flavoured platforms, give the commands below:
+
.. container:: listingblock
.. container:: content
- .. code::
- :number-lines:
+ .. code::
+ :number-lines:
+
+ sudo su - apexuser
+ export APEX_HOME <path to apex installation>
+ export APEX_USER apexuser
- # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)
- # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2)
- >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)
+ .. container:: paragraph
+
+ You can now try to run apex.
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+ :number-lines:
+
+ # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)
+ # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2)
+ >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)
.. container:: colist arabic
.. container:: paragraph
- The engine should start successfully. Assuming the logging levels are
- not change (default level is ``info``), the output should look
- similar to this (last few lines)
+ The engine should start successfully. Assuming the logging levels are set to ``info`` in the built system, the output
+ should look similar to this (last few lines)
.. container:: listingblock
"engineServiceParameters":{
... (1)
"engineParameters":{ (2)
- "engineParameters":{...}, (3)
+ "executorParameters":{...}, (3)
"contextParameters":{...} (4)
+ "taskParameters":[...] (5)
}
},
- "eventInputParameters":{ (5)
- "input1":{ (6)
+ "eventInputParameters":{ (6)
+ "input1":{ (7)
"carrierTechnologyParameters":{...},
"eventProtocolParameters":{...}
},
- "input2":{...}, (7)
+ "input2":{...}, (8)
"carrierTechnologyParameters":{...},
"eventProtocolParameters":{...}
},
- ... (8)
+ ... (9)
},
- "eventOutputParameters":{ (9)
- "output1":{ (10)
+ "eventOutputParameters":{ (10)
+ "output1":{ (11)
"carrierTechnologyParameters":{...},
"eventProtocolParameters":{...}
},
- "output2":{ (11)
+ "output2":{ (12)
"carrierTechnologyParameters":{...},
"eventProtocolParameters":{...}
},
- ... (12)
+ ... (13)
}
}
| | for context schemas, persistence, |
| | etc. |
+-----------------------------------+-----------------------------------+
- | **5** | configuration of the input |
+ | **5** | list of task parameters that |
+ | | should be made available in task |
+ | | logic (optional). |
+ +-----------------------------------+-----------------------------------+
+ | **6** | configuration of the input |
| | interface |
+-----------------------------------+-----------------------------------+
- | **6** | an example input called |
+ | **7** | an example input called |
| | ``input1`` with carrier |
| | technology and event protocol |
+-----------------------------------+-----------------------------------+
- | **7** | an example input called |
+ | **8** | an example input called |
| | ``input2`` with carrier |
| | technology and event protocol |
+-----------------------------------+-----------------------------------+
- | **8** | any further input configuration |
+ | **9** | any further input configuration |
+-----------------------------------+-----------------------------------+
- | **9** | configuration of the output |
+ | **10** | configuration of the output |
| | interface |
+-----------------------------------+-----------------------------------+
- | **10** | an example output called |
+ | **11** | an example output called |
| | ``output1`` with carrier |
| | technology and event protocol |
+-----------------------------------+-----------------------------------+
- | **11** | an example output called |
+ | **12** | an example output called |
| | ``output2`` with carrier |
| | technology and event protocol |
+-----------------------------------+-----------------------------------+
- | **12** | any further output configuration |
+ | **13** | any further output configuration |
+-----------------------------------+-----------------------------------+
Engine Service Parameters
"policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6)
"periodicEventPeriod": 1000, (7)
"engineParameters":{ (8)
- "engineParameters":{...}, (9)
- "contextParameters":{...} (10)
+ "executorParameters":{...}, (9)
+ "contextParameters":{...}, (10)
+ "taskParameters":[...] (11)
}
}
| | for context schemas, persistence, |
| | etc. |
+-----------------------------------+-----------------------------------+
+ | **11** | list of task parameters that |
+ | | should be made available in task |
+ | | logic (optional). |
+ +-----------------------------------+-----------------------------------+
.. container:: paragraph
- Since AVRO uses lazy initialization, this
rejection might only become visible at runtime
+Configure Task Parameters
+#########################
+
+ .. container:: paragraph
+
+ The Task Parameters are added to the configuration as
+ follows:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "engineServiceParameters": {
+ "engineParameters": {
+ "taskParameters": [
+ {
+ "key": "ParameterKey1",
+ "value": "ParameterValue1"
+ },
+ {
+ "taskId": "Task_Act0",
+ "key": "ParameterKey2",
+ "value": "ParameterValue2"
+ }
+ ]
+ }
+ }
+
+ .. container:: paragraph
+
+ TaskParameters can be used to pass parameters from ApexConfig
+ to the policy logic. In the config, these are optional.
+ The list of task parameters provided in the config may be added
+ to the tasks or existing task parameters in the task will be overriden.
+
+ .. container:: paragraph
+
+ If taskId is provided in ApexConfig for an entry, then that
+ parameter is updated only for that particular task. Otherwise,
+ the task parameter is added to all tasks.
+
Carrier Technologies
--------------------
APEX can act as REST client on the input as well as on
the output interface. The media type is
- ``application/json``, so this plugin does only work with
+ ``application/json``, so this plugin only works with
the JSON Event protocol.
REST Client Input
- Maximum port: 65535
- The media type is ``application/json``, so this plugin
- does only work with the JSON Event protocol.
+ only works with the JSON Event protocol.
.. container:: paragraph
APEX can act as REST requestor on the input as well as on
the output interface. The media type is
- ``application/json``, so this plugin does only work with
+ ``application/json``, so this plugin only works with
the JSON Event protocol.
REST Requestor Input
| **4** | a general request timeout |
+-------+---------------------------+
+gRPC IO
+#######
+
+ .. container:: paragraph
+
+ APEX can send requests over gRPC at the output side, and get back
+ response at the input side. This can be used to send requests to CDS
+ over gRPC. The media type is ``application/json``, so this plugin
+ only works with the JSON Event protocol.
+
+gRPC Output
+===========
+
+ .. container:: paragraph
+
+ APEX will connect to a given host to send a request over
+ gRPC.
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "carrierTechnologyParameters": {
+ "carrierTechnology": "GRPC", (1)
+ "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.grpc.GrpcCarrierTechnologyParameters",
+ "parameters": {
+ "host": "cds-blueprints-processor-grpc", (2)
+ "port": 9111, (2')
+ "username": "ccsdkapps", (3)
+ "password": ccsdkapps, (4)
+ "timeout" : 10 (5)
+ }
+ },
+
+ .. container:: colist arabic
+
+ +-------+--------------------------------------------------+
+ | **1** | set GRPC as carrier technology |
+ +-------+--------------------------------------------------+
+ | **2** | the host to which request is sent |
+ +-------+--------------------------------------------------+
+ | **2'**| the value for port |
+ +-------+--------------------------------------------------+
+ | **3** | username required to initiate connection |
+ +-------+--------------------------------------------------+
+ | **4** | password required to initiate connection |
+ +-------+--------------------------------------------------+
+ | **5** | the timeout value for completing the request |
+ +-------+--------------------------------------------------+
+
+ .. container:: paragraph
+
+ Further settings are required on the producer to
+ define the event that is requested, for example:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "eventName": "GRPCRequestEvent", (1)
+ "eventNameFilter": "GRPCRequestEvent", (2)
+ "requestorMode": true, (3)
+ "requestorPeer": "GRPCRequestConsumer", (4)
+ "requestorTimeout": 500 (5)
+
+ .. container:: colist arabic
+
+ +-------+---------------------------+
+ | **1** | the event name |
+ +-------+---------------------------+
+ | **2** | a filter on the event |
+ +-------+---------------------------+
+ | **3** | the mode of the requestor |
+ +-------+---------------------------+
+ | **4** | a peer for the requestor |
+ +-------+---------------------------+
+ | **5** | a general request timeout |
+ +-------+---------------------------+
+
+gRPC Input
+==========
+
+ .. container:: paragraph
+
+ APEX will connect to the host specified in the producer
+ side, anad take in response back at the consumer side.
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "carrierTechnologyParameters": {
+ "carrierTechnology": "GRPC", (1)
+ "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.grpc.GrpcCarrierTechnologyParameters"
+ },
+
+ .. container:: colist arabic
+
+ +-------+------------------------------------------+
+ | **1** | set GRPC as carrier technology |
+ +-------+------------------------------------------+
+
+ .. container:: paragraph
+
+ Further settings are required on the consumer to
+ define the event that is requested, for example:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "eventNameFilter": "GRPCResponseEvent", (1)
+ "requestorMode": true, (2)
+ "requestorPeer": "GRPCRequestProducer", (3)
+ "requestorTimeout": 500 (4)
+
+ .. container:: colist arabic
+
+ +-------+---------------------------+
+ | **1** | a filter on the event |
+ +-------+---------------------------+
+ | **2** | the mode of the requestor |
+ +-------+---------------------------+
+ | **3** | a peer for the requestor |
+ +-------+---------------------------+
+ | **4** | a general request timeout |
+ +-------+---------------------------+
+
Event Protocols, Format and Encoding
------------------------------------
.. container:: title
- Field Schema types
+ Field Schema types
.. container:: paragraph
APEX natively supports schema definitions in ``Java`` and ``Avro``.
-
+
.. container:: paragraph
``Java`` schema definitions are simply the name of a Java Class. There are some restrictions:
| | | |
| | | at *08:41:06 |
| | .. container:: content | GMT* on *Monday, |
- | .. container:: content | | 02 January |
+ | .. container:: content | | 02 January |
| | .. code:: | 2017*. |
| | | |
- | | { | Sale is not |
+ | | { | Sale is not |
| .. code:: | "nameSpace": "com.hyperm", | authorized. Uses |
| | "name": "SALE_AUTH", | the |
| | "version": "0.0.1", | ``MorningBoozeCheck`` |
| { | "source": "", | |
- | "nameSpace": "com.hyperm", | "target": "", | task. |
+ | "nameSpace": "com.hyperm", | "target": "", | task. |
| "name": "SALE_INPUT", | "amount": 1249, | |
| "version": "0.0.1", | "assistant_ID":12, | Note this test |
| "time": 1483346466000, | "authorised": false, | is copied from |
| "sale_ID": 99999992, | "branch_ID": 2, | Step 1 above, |
- | "amount": 1249, | "item_ID": 1012, | and demonstrates |
+ | "amount": 1249, | "item_ID": 1012, | and demonstrates |
| "item_ID": 1012, | "message": "Sale not authorised by policy ta | that the |
| "quantity": 1, | sk MorningBoozeCheck for time 08:41:06 GMT.| original |
| "assistant_ID": 12, | Alcohol can not be sold between 00:00:00 | ``MorningBoozeCheck`` |
| "branch_ID": 2 | GMT and 11:30:00 GMT", | |
| } | "notes": null, | task is |
- | | "quantity": 1, | executed. |
+ | | "quantity": 1, | executed. |
| | "sale_ID": 99999992, | |
| | "time": 1483346466000 | |
| | } | |
The standard logging configuration defines a context *APEX*,
which is used in the standard output pattern. The location
- for log files is defined in the property ``VAR_LOG`` and set
+ for log files is defined in the property ``logDir`` and set
to ``/var/log/onap/policy/apex-pdp``. The standard status
listener is set to *NOP* and the overall logback
configuration is set to no debug.
<statusListener class="ch.qos.logback.core.status.NopStatusListener" />
<contextName>Apex</contextName>
- <property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />
+ <property name="logDir" value="/var/log/onap/policy/apex-pdp/" />
...appenders
...loggers
:number-lines:
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex.log</file>
+ <file>${logDir}/apex.log</file>
<encoder>
<pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>
</encoder>
:number-lines:
<appender name="CTXT_FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex_ctxt.log</file>
+ <file>${logDir}/apex_ctxt.log</file>
<encoder>
<pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>
</encoder>
.. code::
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>${VAR_LOG}/apex.log</file>
+ <file>${logDir}/apex.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<!-- rollover daily -->
<!-- <fileNamePattern>xstream-%d{yyyy-MM-dd}.%i.txt</fileNamePattern> -->
- <fileNamePattern>${VAR_LOG}/apex_%d{yyyy-MM-dd}.%i.log.gz
+ <fileNamePattern>${logDir}/apex_%d{yyyy-MM-dd}.%i.log.gz
</fileNamePattern>
<maxHistory>4</maxHistory>
<timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
<appender name="CTXT-FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>${VAR_LOG}/apex_ctxt.log</file>
+ <file>${logDir}/apex_ctxt.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
- <fileNamePattern>${VAR_LOG}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz
+ <fileNamePattern>${logDir}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz
</fileNamePattern>
<maxHistory>4</maxHistory>
<timeBasedFileNamingAndTriggeringPolicy
<statusListener class="ch.qos.logback.core.status.NopStatusListener" />
<contextName>Apex</contextName>
- <property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />
+ <property name="logDir" value="/var/log/onap/policy/apex-pdp/" />
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
</appender>
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex.log</file>
+ <file>${logDir}/apex.log</file>
<encoder>
<pattern>
%d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
<statusListener class="ch.qos.logback.core.status.NopStatusListener" />
<contextName>Apex</contextName>
- <property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />
+ <property name="logDir" value="/var/log/onap/policy/apex-pdp/" />
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex.log</file>
+ <file>${logDir}/apex.log</file>
<encoder>
<pattern>
%d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
(``cmd`` on Windows). Then use the APEX application launcher to
start the client.
- .. important::
+ .. important::
APEX engine needs to run first
The example assumes that an APEX engine configured for *produce* carrier technology Websocket and *JSON* event protocol is executed first.
(``cmd`` on Windows). Then use the APEX application launcher to
start the client.
- .. important::
+ .. important::
APEX engine needs to run first
The example assumes that an APEX engine configured for *consume* carrier technology Websocket and *JSON* event
protocol is executed first.
Code Review / policy / parent.git / blobdiff