From cc0e917ff2fba38585b0064517409968f66a2a7e Mon Sep 17 00:00:00 2001 From: "a.sreekumar" Date: Mon, 16 Mar 2020 13:36:45 +0000 Subject: APEX Documentation changes for Frankfurt release Change-Id: Idb7f768f04269a25222ed649e2e59973286aefbc Issue-ID: POLICY-2424 Signed-off-by: a.sreekumar --- docs/apex/APEX-OnapPf-Guide.rst | 96 ++++++++--------- docs/apex/APEX-Policy-Guide.rst | 104 +++++++++++++----- docs/apex/APEX-User-Manual.rst | 233 ++++++++++++++++++++++++++++++++++++---- 3 files changed, 332 insertions(+), 101 deletions(-) (limited to 'docs/apex') 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 | .. 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 `__ + 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 ------------------------------------ -- cgit 1.2.3-korg