summaryrefslogtreecommitdiffstats
path: root/docs/apex
diff options
context:
space:
mode:
authora.sreekumar <ajith.sreekumar@est.tech>2020-03-16 13:36:45 +0000
committera.sreekumar <ajith.sreekumar@est.tech>2020-03-19 09:48:42 +0000
commitcc0e917ff2fba38585b0064517409968f66a2a7e (patch)
tree5cf701b0da821ef05001707785cbbb4d261ee9cf /docs/apex
parente78b9eff25270b8a83a232329db034fbb38eaa02 (diff)
APEX Documentation changes for Frankfurt release
Change-Id: Idb7f768f04269a25222ed649e2e59973286aefbc Issue-ID: POLICY-2424 Signed-off-by: a.sreekumar <ajith.sreekumar@est.tech>
Diffstat (limited to 'docs/apex')
-rw-r--r--docs/apex/APEX-OnapPf-Guide.rst96
-rw-r--r--docs/apex/APEX-Policy-Guide.rst104
-rw-r--r--docs/apex/APEX-User-Manual.rst233
3 files changed, 332 insertions, 101 deletions
diff --git a/docs/apex/APEX-OnapPf-Guide.rst b/docs/apex/APEX-OnapPf-Guide.rst
index 5e75f325..0fe38025 100644
--- a/docs/apex/APEX-OnapPf-Guide.rst
+++ b/docs/apex/APEX-OnapPf-Guide.rst
@@ -264,51 +264,38 @@ Build a Docker Image
:number-lines:
#
- # Docker file to build an image that runs APEX on Java 8 in alpine
+ # Docker file to build an image that runs APEX on Java 11 or better in alpine
#
- FROM onap/policy-base-alpine:1.4.0
+ FROM onap/policy-jre-alpine:2.0.1
LABEL maintainer="Policy Team"
- ARG BUILD_VERSION=${BUILD_VERSION}
ARG POLICY_LOGS=/var/log/onap/policy/apex-pdp
-
- ENV BUILD_VERSION ${BUILD_VERSION}
- ENV POLICY_HOME=/opt/app/policy
- ENV POLICY_APEX_PDP_HOME=${POLICY_HOME}/apex-pdp
- ENV POLICY_LOGS=${POLICY_LOGS}
+ ENV POLICY_HOME=/opt/app/policy/apex-pdp
+ ENV POLICY_LOGS=$POLICY_LOGS
RUN apk add --no-cache \
- vim \
- iproute2 \
- iputils
-
- # Create apex user and group
- RUN addgroup -S apexuser && adduser -S apexuser -G apexuser
-
-
- # Add Apex-specific directories and set ownership as the Apex admin user
- RUN mkdir -p ${POLICY_APEX_PDP_HOME} \
- && mkdir -p ${POLICY_LOGS} \
- && chown -R apexuser:apexuser ${POLICY_LOGS}
-
- # Unpack the tarball
- RUN mkdir /packages
- COPY apex-pdp-package-full.tar.gz /packages
- RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory ${POLICY_APEX_PDP_HOME} \
- && rm /packages/apex-pdp-package-full.tar.gz
-
- # Ensure everything has the correct permissions
- RUN find /opt/app -type d -perm 755 \
+ vim \
+ iproute2 \
+ iputils \
+ && addgroup -S apexuser && adduser -S apexuser -G apexuser \
+ && mkdir -p $POLICY_HOME \
+ && mkdir -p $POLICY_LOGS \
+ && chown -R apexuser:apexuser $POLICY_LOGS \
+ && mkdir /packages
+
+ COPY /maven/apex-pdp-package-full.tar.gz /packages
+ RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory $POLICY_HOME \
+ && rm /packages/apex-pdp-package-full.tar.gz \
+ && find /opt/app -type d -perm 755 \
&& find /opt/app -type f -perm 644 \
- && chmod a+x ${POLICY_APEX_PDP_HOME}/bin/*
-
- # Copy examples to Apex user area
- RUN cp -pr ${POLICY_APEX_PDP_HOME}/examples /home/apexuser \
- && chown -R apexuser:apexuser /home/apexuser/*
+ && chmod 755 $POLICY_HOME/bin/* \
+ && cp -pr $POLICY_HOME/examples /home/apexuser \
+ && chown -R apexuser:apexuser /home/apexuser/* $POLICY_HOME \
+ && chmod 644 $POLICY_HOME/etc/*
USER apexuser
- ENV PATH ${POLICY_APEX_PDP_HOME}/bin:$PATH
+ ENV PATH $POLICY_HOME/bin:$PATH
WORKDIR /home/apexuser
@@ -350,19 +337,20 @@ Format of the configuration file (OnapPfConfig.json) explained
"pdpStatusParameters":{
"timeIntervalMs": 120000, (3)
"pdpType":"apex", (4)
+ "pdpGroup":"defaultGroup", (5)
"description":"Pdp Heartbeat",
- "supportedPolicyTypes":[{"name":"onap.policies.controlloop.operational.Apex","version":"1.0.0"}] (5)
+ "supportedPolicyTypes":[{"name":"onap.policies.controlloop.operational.Apex","version":"1.0.0"}] (6)
},
"topicParameterGroup": {
- "topicSources" : [{ (6)
- "topic" : "POLICY-PDP-PAP", (7)
- "servers" : [ "message-router" ], (8)
- "topicCommInfrastructure" : "dmaap" (9)
+ "topicSources" : [{ (7)
+ "topic" : "POLICY-PDP-PAP", (8)
+ "servers" : [ "message-router" ], (9)
+ "topicCommInfrastructure" : "dmaap" (10)
}],
- "topicSinks" : [{ (10)
- "topic" : "POLICY-PDP-PAP", (11)
- "servers" : [ "message-router" ], (12)
- "topicCommInfrastructure" : "dmaap" (13)
+ "topicSinks" : [{ (11)
+ "topic" : "POLICY-PDP-PAP", (12)
+ "servers" : [ "message-router" ], (13)
+ "topicCommInfrastructure" : "dmaap" (14)
}]
}
}
@@ -383,35 +371,37 @@ Format of the configuration file (OnapPfConfig.json) explained
+-----------------------------------+-------------------------------------------------+
| **4** | Type of the pdp. |
+-----------------------------------+-------------------------------------------------+
- | **5** | List of policy types supported by |
+ | **5** | The group to which the pdp belong to. |
+ +-----------------------------------+-------------------------------------------------+
+ | **6** | List of policy types supported by |
| | the PDP. A trailing “.*” can be used to |
| | specify multiple policy types; for example, |
| | “onap.policies.controlloop.operational.apex.*” |
| | would match any policy type beginning with |
| | “onap.policies.controlloop.operational.apex.” |
+-----------------------------------+-------------------------------------------------+
- | **6** | List of topics' details from |
+ | **7** | List of topics' details from |
| | which messages are received. |
+-----------------------------------+-------------------------------------------------+
- | **7** | Topic name of the source to which |
+ | **8** | Topic name of the source to which |
| | PDP-A listens to for messages |
| | from PAP. |
+-----------------------------------+-------------------------------------------------+
- | **8** | List of servers for the source |
+ | **9** | List of servers for the source |
| | topic. |
+-----------------------------------+-------------------------------------------------+
- | **9** | The source topic infrastructure. |
+ | **10** | The source topic infrastructure. |
| | For e.g. dmaap, noop, ueb |
+-----------------------------------+-------------------------------------------------+
- | **10** | List of topics' details to which |
+ | **11** | List of topics' details to which |
| | messages are sent. |
+-----------------------------------+-------------------------------------------------+
- | **11** | Topic name of the sink to which |
+ | **12** | Topic name of the sink to which |
| | PDP-A sends messages. |
+-----------------------------------+-------------------------------------------------+
- | **12** | List of servers for the sink |
+ | **13** | List of servers for the sink |
| | topic. |
+-----------------------------------+-------------------------------------------------+
- | **13** | The sink topic infrastructure. |
+ | **14** | The sink topic infrastructure. |
| | For e.g. dmaap, noop, ueb |
+-----------------------------------+-------------------------------------------------+
diff --git a/docs/apex/APEX-Policy-Guide.rst b/docs/apex/APEX-Policy-Guide.rst
index f76ed138..c7e8ad5c 100644
--- a/docs/apex/APEX-Policy-Guide.rst
+++ b/docs/apex/APEX-Policy-Guide.rst
@@ -664,6 +664,13 @@ Concept: TaskParameter
values in the configuration information passed to APEX
engines.
+ .. container:: paragraph
+
+ The *taskParameters* field is specified under *engineParameters*
+ in the ApexConfig. It can contain one or more task parameters, where each
+ item can contain the parameter key, value as well as the taskId to which it is associated.
+ If the taskId is not specified, then the parameters are added to all tasks.
+
Concept: Logic
##############
@@ -1567,6 +1574,22 @@ Writing APEX Task Selection Logic
| | | | .getOutFieldSchemaHelper("authorised") |
| | | | .createNewInstance("false"); |
+------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+
+| parameters | Fields | java.util.Map <String,String> | .. container:: paragraph |
+| | | | |
+| | | | All parameters in the current task. This is implemented as a standard Java Map. |
+| | | | |
+| | | | .. container:: |
+| | | | |
+| | | | .. container:: content |
+| | | | |
+| | | | .. container:: paragraph |
+| | | | |
+| | | | **Example:** |
+| | | | |
+| | | | .. code:: javascript |
+| | | | |
+| | | | executor.parameters.get("ParameterKey1")) |
++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+
| ContextAlbum getContextAlbum(String ctxtAlbumName ) | .. container:: paragraph |
| | |
| | A utility method to retrieve a ``ContextAlbum`` for use in the task. |
@@ -1604,32 +1627,13 @@ Logic Cheatsheet
Examples given here use Javascript (if not stated otherwise),
other execution environments will be similar.
-Add Nashorn
-###########
-
- .. container:: paragraph
-
- First line in the logic use this import.
-
- .. container:: listingblock
-
- .. container:: title
-
- JS Nashorn
-
- .. container:: content
-
- .. code:: javascript
-
- load("nashorn:mozilla_compat.js");
-
Finish Logic with Success or Error
##################################
.. container:: paragraph
To finish logic, i.e. return to APEX, with success use the
- following lines close to the end of the logic.
+ following line close to the end of the logic.
.. container:: listingblock
@@ -1641,8 +1645,7 @@ Finish Logic with Success or Error
.. code:: javascript
- var returnValueType = Java.type("java.lang.Boolean");
- var returnValue = new returnValueType(true);
+ true;
.. container:: paragraph
@@ -1658,8 +1661,7 @@ Finish Logic with Success or Error
.. code:: javascript
- var returnValueType = Java.type("java.lang.Boolean");
- var returnValue = new returnValueType(false);
+ false;
Logic Logging
#############
@@ -1731,6 +1733,43 @@ Logic Logging
rootLogger.error("Serious error in logic detected: " + executor.subject.id);
+Accessing TaskParameters
+########################
+
+ .. container:: paragraph
+
+ TaskParameters available in a Task can be accessed in the logic.
+ The parameters in each task are made available at the executor level.
+ This example assumes a parameter with key ``ParameterKey1``.
+
+ .. container:: listingblock
+
+ .. container:: title
+
+ JS TaskParameter value
+
+ .. container:: content
+
+ .. code:: javascript
+
+ executor.parameters.get("ParameterKey1"))
+
+ .. container:: paragraph
+
+ Alternatively, the task parameters can also be accessed from the task object.
+
+ .. container:: listingblock
+
+ .. container:: title
+
+ JS TaskParameter value using task object
+
+ .. container:: content
+
+ .. code:: javascript
+
+ executor.subject.task.getTaskParameters.get("ParameterKey1").getTaskParameterValue()
+
Local Variable for Infields
###########################
@@ -2057,6 +2096,19 @@ Using Java in Scripting Logic
Policy Examples
^^^^^^^^^^^^^^^
+Sample APEX Policy in TOSCA format
+----------------------------------
+
+ .. container:: paragraph
+
+ An example APEX policy in TOSCA format for the vCPE
+ use case can be found here:
+
+ .. container:: ulist
+
+ - `APEX TOSCA Policy
+ vCPE <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.apex.policy.operational.input.tosca.json>`__
+
My First Policy
---------------
@@ -2124,8 +2176,8 @@ Decision Maker
.. container::
:name: footer-text
- 2.0.0-SNAPSHOT
- Last updated 2018-09-04 16:04:24 IST
+ 2.3.0-SNAPSHOT
+ Last updated 2020-03-16 16:04:24 GMT
.. |APEX Policy Matrix| image:: images/apex-intro/ApexPolicyMatrix.png
.. |APEX Policy Model for Execution| image:: images/apex-policy-model/UmlPolicyModels.png
diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst
index f33ad5ee..10201c0f 100644
--- a/docs/apex/APEX-User-Manual.rst
+++ b/docs/apex/APEX-User-Manual.rst
@@ -1461,31 +1461,32 @@ General Configuration Format
"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)
}
}
@@ -1506,31 +1507,35 @@ General Configuration Format
| | 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
@@ -1557,8 +1562,9 @@ 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)
}
}
@@ -1617,6 +1623,10 @@ Engine Service Parameters
| | for context schemas, persistence, |
| | etc. |
+-----------------------------------+-----------------------------------+
+ | **11** | list of task parameters that |
+ | | should be made available in task |
+ | | logic (optional). |
+ +-----------------------------------+-----------------------------------+
.. container:: paragraph
@@ -2097,6 +2107,49 @@ Configure AVRO Schema Handler
- 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
--------------------
@@ -2815,7 +2868,7 @@ REST Client IO
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
@@ -2948,7 +3001,7 @@ REST Server IO
- 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
@@ -3124,7 +3177,7 @@ REST Requestor IO
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
@@ -3268,6 +3321,142 @@ REST Requestor Output
| **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
------------------------------------