X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapex%2FAPEX-User-Manual.rst;h=c0a7aaca054acae4fca299b0f1555489abe1fb67;hb=688a2dd3a681c28ac48ad737316c2dc1dff08526;hp=b10dcf8a0cafac142e310edec47f0425472315fd;hpb=75e2bbf70872274890757c8de6c3c6262cb1e3bc;p=policy%2Fparent.git diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst index b10dcf8a..c0a7aaca 100644 --- a/docs/apex/APEX-User-Manual.rst +++ b/docs/apex/APEX-User-Manual.rst @@ -1,6 +1,7 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _apex-user-manual-label: APEX User Manual **************** @@ -8,8 +9,8 @@ APEX User Manual .. contents:: :depth: 3 -Installation -^^^^^^^^^^^^ +Installation of Apex +^^^^^^^^^^^^^^^^^^^^ Requirements ------------ @@ -223,67 +224,67 @@ Build APEX installation. The following example show how to change to the target directory and how it should look like. -+----------------------------------------------------------------------------------------------------------------------------+ -| Unix, Cygwin | -+============================================================================================================================+ -| .. container:: | -| | -| .. 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* | -| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* | -| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* | -| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ | -| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* | -| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* | -| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* | -| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ | -+----------------------------------------------------------------------------------------------------------------------------+ - -+--------------------------------------------------------------------------------------------------------+ -| Windows | -+========================================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. container:: content | -| | -| .. code:: | -| :number-lines: | -| | -| 03/09/2018 11:55 . | -| 03/09/2018 11:55 .. | -| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz | -| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb | -| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar | -| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes | -| 03/09/2018 11:54 archive-tmp | -| 03/09/2018 11:54 89 checkstyle-cachefile | -| 03/09/2018 11:54 10,621 checkstyle-checker.xml | -| 03/09/2018 11:54 584 checkstyle-header.txt | -| 03/09/2018 11:54 86 checkstyle-result.xml | -| 03/09/2018 11:54 classes | -| 03/09/2018 11:54 dependency-maven-plugin-markers | -| 03/09/2018 11:54 etc | -| 03/09/2018 11:54 examples | -| 03/09/2018 11:55 install_hierarchy | -| 03/09/2018 11:54 maven-archiver | -| 8 File(s) 292,652,686 bytes | -| 9 Dir(s) 14,138,720,256 bytes free | -+--------------------------------------------------------------------------------------------------------+ ++---------------------------------------------------------------------------------------------------------------------+ +| Unix, Cygwin | ++=====================================================================================================================+ +| .. 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* | +| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* | +| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* | +| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ | +| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* | +| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* | +| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* | +| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ | ++---------------------------------------------------------------------------------------------------------------------+ + ++----------------------------------------------------------------------------------------------+ +| Windows | ++==============================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. container:: content | +| | +| .. code:: | +| :number-lines: | +| | +| 03/09/2018 11:55 . | +| 03/09/2018 11:55 .. | +| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz | +| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar | +| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes | +| 03/09/2018 11:54 archive-tmp | +| 03/09/2018 11:54 89 checkstyle-cachefile | +| 03/09/2018 11:54 10,621 checkstyle-checker.xml | +| 03/09/2018 11:54 584 checkstyle-header.txt | +| 03/09/2018 11:54 86 checkstyle-result.xml | +| 03/09/2018 11:54 classes | +| 03/09/2018 11:54 dependency-maven-plugin-markers | +| 03/09/2018 11:54 etc | +| 03/09/2018 11:54 examples | +| 03/09/2018 11:55 install_hierarchy | +| 03/09/2018 11:54 maven-archiver | +| 8 File(s) 292,652,686 bytes | +| 9 Dir(s) 14,138,720,256 bytes free | ++----------------------------------------------------------------------------------------------+ Install APEX ------------ @@ -324,33 +325,33 @@ Install with DPKG the standard APEX start scripts to run APEX with this user’s permissions. -+--------------------------------------------------------------------------------------+ -| DPKG Installation | -+======================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. container:: content | -| | -| .. code:: | -| :number-lines: | -| | -| # 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 ... | -| ********************preinst******************* | -| arguments install | -| ********************************************** | -| creating group apexuser . . . | -| creating user apexuser . . . | -| Unpacking apex-uservice (2.0.0-SNAPSHOT) ... | -| Setting up apex-uservice (2.0.0-SNAPSHOT) ... | -| ********************postinst**************** | -| arguments configure | -| *********************************************** | -+--------------------------------------------------------------------------------------+ ++-------------------------------------------------------------------------------+ +| DPKG Installation | ++===============================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. container:: content | +| | +| .. code:: | +| :number-lines: | +| | +| # 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 ... | +| ********************preinst******************* | +| arguments install | +| ********************************************** | +| creating group apexuser . . . | +| creating user apexuser . . . | +| Unpacking apex-uservice (2.0.0-SNAPSHOT) ... | +| Setting up apex-uservice (2.0.0-SNAPSHOT) ... | +| ********************postinst**************** | +| arguments configure | +| *********************************************** | ++-------------------------------------------------------------------------------+ .. container:: paragraph @@ -397,26 +398,8 @@ Install Manually from Archive (Windows, 7Zip, GUI) right click on the file and extract the ``tar`` archive. Note: the screenshots might show an older version than you have. - .. container:: imageblock - - .. container:: content - - |Extract the TAR archive| - - .. container:: paragraph - - The right-click on the new created TAR file and extract the actual - APEX distribution. - - .. container:: imageblock - - .. container:: content - - |Extract the APEX distribution| - - .. container:: paragraph - - Inside the new APEX folder you see the main directories: ``bin``, + Now, right-click on the new created TAR file and extract the actual + APEX distribution. Inside the new APEX folder you will see the main directories: ``bin``, ``etc``, ``examples``, ``lib``, and ``war`` .. container:: paragraph @@ -538,67 +521,67 @@ Build and Install Manually (Unix, Windows, Cygwin) installation. The following example show how to change to the target directory and how it should look like. -+-----------------------------------------------------------------------------------------------------------------------------+ -| Unix, Cygwin | -+=============================================================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. code:: | -| :number-lines: | -| | -| # cd packages/apex-pdp-package-full/target | -| # ls -l | -| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* | -| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* | -| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* | -| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ | -| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* | -| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* | -| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* | -| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ | -| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ | -+-----------------------------------------------------------------------------------------------------------------------------+ - -+-----------------------------------------------------------------------------------------------------------------------------+ -| Windows | -+=============================================================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. code:: | -| :number-lines: | -| | -| >cd packages\apex-pdp-package-full\target | -| >dir | -| 03/09/2018 11:55 . | -| 03/09/2018 11:55 .. | -| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz | -| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb | -| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar | -| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes | -| 03/09/2018 11:54 archive-tmp | -| 03/09/2018 11:54 89 checkstyle-cachefile | -| 03/09/2018 11:54 10,621 checkstyle-checker.xml | -| 03/09/2018 11:54 584 checkstyle-header.txt | -| 03/09/2018 11:54 86 checkstyle-result.xml | -| 03/09/2018 11:54 classes | -| 03/09/2018 11:54 dependency-maven-plugin-markers | -| 03/09/2018 11:54 etc | -| 03/09/2018 11:54 examples | -| 03/09/2018 11:55 install_hierarchy | -| 03/09/2018 11:54 maven-archiver | -| 8 File(s) 292,652,686 bytes | -| 9 Dir(s) 14,138,720,256 bytes free | -+-----------------------------------------------------------------------------------------------------------------------------+ ++--------------------------------------------------------------------------------------------------------------------+ +| Unix, Cygwin | ++====================================================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. code:: | +| :number-lines: | +| | +| # cd packages/apex-pdp-package-full/target | +| # ls -l | +| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* | +| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* | +| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* | +| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ | +| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* | +| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* | +| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* | +| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ | ++--------------------------------------------------------------------------------------------------------------------+ + ++---------------------------------------------------------------------------------------------+ +| Windows | ++=============================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. code:: | +| :number-lines: | +| | +| >cd packages\apex-pdp-package-full\target | +| >dir | +| 03/09/2018 11:55 . | +| 03/09/2018 11:55 .. | +| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz | +| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar | +| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes | +| 03/09/2018 11:54 archive-tmp | +| 03/09/2018 11:54 89 checkstyle-cachefile | +| 03/09/2018 11:54 10,621 checkstyle-checker.xml | +| 03/09/2018 11:54 584 checkstyle-header.txt | +| 03/09/2018 11:54 86 checkstyle-result.xml | +| 03/09/2018 11:54 classes | +| 03/09/2018 11:54 dependency-maven-plugin-markers | +| 03/09/2018 11:54 etc | +| 03/09/2018 11:54 examples | +| 03/09/2018 11:55 install_hierarchy | +| 03/09/2018 11:54 maven-archiver | +| 8 File(s) 292,652,686 bytes | +| 9 Dir(s) 14,138,720,256 bytes free | ++---------------------------------------------------------------------------------------------+ .. container:: paragraph @@ -617,7 +600,7 @@ Installation Layout .. container:: content - :: + :: $APEX_HOME ├───bin (1) @@ -943,10 +926,10 @@ Verify Installation - run Engine .. container:: paragraph A simple verification of an APEX installation can be done by - simply starting the APEX engine without any configuration. On + simply starting the APEX engine without specifying a tosca policy. On Unix (or Cygwin) start the engine using - ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the engine - using ``%APEX_HOME%\bin\apexEngine.bat``. The engine will fail + ``$APEX_HOME/bin/apexApps.sh engine``. On Windows start the engine + using ``%APEX_HOME%\bin\apexApps.bat engine``. The engine will fail to fully start. However, if the output looks similar to the following line, the APEX installation is realized. @@ -958,21 +941,16 @@ Verify Installation - run Engine :number-lines: Starting Apex service with parameters [] . . . - start of Apex service failed: Apex configuration file was not specified as an argument - 2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed - org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument - at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267) - at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161) - at org.onap.policy.apex.service.engine.main.ApexMain.(ApexMain.java:68) - at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165) - 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 + start of Apex service failed. + org.onap.policy.apex.model.basicmodel.concepts.ApexException: Arguments validation failed. + at org.onap.policy.apex.service.engine.main.ApexMain.populateApexParameters(ApexMain.java:238) + at org.onap.policy.apex.service.engine.main.ApexMain.(ApexMain.java:86) + at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:351) + Caused by: org.onap.policy.apex.model.basicmodel.concepts.ApexException: Tosca Policy file was not specified as an argument + at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:242) + at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:172) + at org.onap.policy.apex.service.engine.main.ApexMain.populateApexParameters(ApexMain.java:235) + ... 2 common frames omitted Verify Installation - run an Example #################################### @@ -1007,7 +985,9 @@ Verify Installation - run an Example .. container:: paragraph - You can now try to run apex. + Create a Tosca Policy for the SampleDomain example using ApexCliToscaEditor + as explained in the section "The APEX CLI Tosca Editor". Assume the tosca policy name is SampleDomain_tosca.json. + You can then try to run apex using the ToscaPolicy. .. container:: listingblock @@ -1016,18 +996,15 @@ Verify Installation - run an Example .. 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) + # $APEX_HOME/bin/apexApps.sh engine -p $APEX_HOME/examples/SampleDomain_tosca.json (1) + >%APEX_HOME%\bin\apexApps.bat engine -p %APEX_HOME%\examples\SampleDomain_tosca.json(2) .. container:: colist arabic +-------+---------+ | **1** | UNIX | +-------+---------+ - | **2** | Cygwin | - +-------+---------+ - | **3** | Windows | + | **2** | Windows | +-------+---------+ .. container:: paragraph @@ -1042,7 +1019,7 @@ Verify Installation - run an Example .. code:: :number-lines: - Starting Apex service with parameters [-c, v:/dev/ericsson/apex/onap/apex-pdp/packages/apex-pdp-package-full/target/install_hierarchy/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json] . . . + Starting Apex service with parameters [-p, /home/ubuntu/apex/SampleDomain_tosca.json] . . . 2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 . 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 . 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 . @@ -1076,36 +1053,36 @@ Verify Installation - run an Example the console. Pasting the input event multiple times will produce output events with different values. -+-------------------------------------------------------------+-------------------------------------------------------------+ -| Input Event | Example Output Event | -+=============================================================+=============================================================+ -| .. container:: | .. container:: | -| | | -| .. container:: content | .. container:: content | -| | | -| .. code:: | .. code:: | -| :number-lines: | :number-lines: | -| | | -| { | { | -| "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", | -| "name": "Event0000", | "version": "0.0.1", | -| "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", | -| "source": "test", | "source": "Act", | -| "target": "apex", | "target": "Outside", | -| "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, | -| "TestMatchCase": 0, | "TestActStateTime": 1536157104627, | -| "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, | -| "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, | -| } | "TestEstablishCaseSelected": 0, | -| | "TestEstablishStateTime": 1536157104623, | -| | "TestMatchCase": 0, | -| | "TestMatchCaseSelected": 1, | -| | "TestMatchStateTime": 1536157104620, | -| | "TestSlogan": "Test slogan for External Event0", | -| | "TestTemperature": 9080.866, | -| | "TestTimestamp": 1469781869269 | -| | } | -+-------------------------------------------------------------+-------------------------------------------------------------+ ++----------------------------------------------------------+----------------------------------------------------------+ +| Input Event | Example Output Event | ++==========================================================+==========================================================+ +| .. container:: | .. container:: | +| | | +| .. container:: content | .. container:: content | +| | | +| .. code:: | .. code:: | +| :number-lines: | :number-lines: | +| | | +| { | { | +| "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", | +| "name": "Event0000", | "version": "0.0.1", | +| "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", | +| "source": "test", | "source": "Act", | +| "target": "apex", | "target": "Outside", | +| "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, | +| "TestMatchCase": 0, | "TestActStateTime": 1536157104627, | +| "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, | +| "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, | +| } | "TestEstablishCaseSelected": 0, | +| | "TestEstablishStateTime": 1536157104623, | +| | "TestMatchCase": 0, | +| | "TestMatchCaseSelected": 1, | +| | "TestMatchStateTime": 1536157104620, | +| | "TestSlogan": "Test slogan for External Event0", | +| | "TestTemperature": 9080.866, | +| | "TestTimestamp": 1469781869269 | +| | } | ++----------------------------------------------------------+----------------------------------------------------------+ .. container:: paragraph @@ -1166,18 +1143,7 @@ Verify a Full Installation - REST Client Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL ``http://localhost:18989/``. This will connect the - browser to the started REST client. Click on the "Policy Editor" button and the Policy Editor start screen should be as - follows. - -.. container:: imageblock - - .. container:: content - - |Policy Editor Start Screen| - - .. container:: title - - Figure 1. Policy Editor Start Screen + browser to the started REST client. Click on the "Policy Editor" button and the Policy Editor start screen should appear. .. container:: paragraph @@ -1185,18 +1151,7 @@ Verify a Full Installation - REST Client ``Open``. In the opened dialog, go to the directory where APEX is installed, then ``examples``, ``models``, ``SampleDomain``, and there select the file ``SamplePolicyModelJAVA.json``. This will load the - policy model used to verify the policy engine (see above). Once - loaded, the screen should look as follows. - -.. container:: imageblock - - .. container:: content - - |Policy Editor with loaded SampleDomain Policy Model| - - .. container:: title - - Figure 2. Policy Editor with loaded SampleDomain Policy Model + policy model used to verify the policy engine (see above). .. container:: paragraph @@ -1279,25 +1234,21 @@ Run in ONAP Running APEX from the ONAP docker repository only requires 2 commands: - .. container:: olist arabic + 1. Log into the ONAP docker repo - #. Log into the ONAP docker repo + .. container:: listingblock - .. container:: listingblock - - .. container:: content + .. container:: content :: docker login -u docker -p docker nexus3.onap.org:10003 - .. container:: olist arabic + 2. Run the APEX docker image - #. Run the APEX docker image + .. container:: listingblock - .. container:: listingblock - - .. container:: content + .. container:: content :: @@ -1365,6 +1316,51 @@ Build a Docker Image ENV PATH /opt/app/policy/apex-pdp/bin:$PATH WORKDIR /home/apexuser +Running APEX in Standalone mode +------------------------------- + + .. container:: paragraph + + APEX Engine can run in standalone mode by taking in a ToscaPolicy + as an argument and executing it. + Assume there is a tosca policy named ToscaPolicy.json in APEX_HOME directory + This policy can be executed in standalone mode using any of the below methods. + +Run in an APEX installation +########################### + + .. container:: listingblock + + .. container:: content + + .. code:: + :number-lines: + + # $APEX_HOME/bin/apexApps.sh engine -p $APEX_HOME/ToscaPolicy.json(1) + >%APEX_HOME%\bin\apexApps.bat engine -p %APEX_HOME%\ToscaPolicy.json(2) + +.. container:: colist arabic + + +-------+---------+ + | **1** | UNIX | + +-------+---------+ + | **2** | Windows | + +-------+---------+ + +Run in a docker container +######################### + + .. container:: listingblock + + .. container:: content + + .. code:: + :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 \ + -c "/opt/app/policy/apex-pdp/bin/apexEngine.sh -p /tmp/policy/ToscaPolicy.json" + APEX Configurations Explained ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1386,7 +1382,7 @@ Introduction to APEX Configuration .. container:: content - |APEX Configuration Matrix| + .. image:: images/apex-intro/ApexEngineConfig.png .. container:: title @@ -1517,8 +1513,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) @@ -1560,13 +1555,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 | @@ -1749,6 +1738,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 ############# @@ -2002,11 +2037,37 @@ Context Handlers APEX provides plugins for each of the main areas. -Configure AVRO Schema Handler -############################# +Configure Context Schema Handler +################################ .. container:: paragraph + There are 2 choices available for defining schema: JSON & AVRO. + JSON based schemas are recommended because of the flexibility, better tooling & easier integration. + + The JSON schema handler is added to the configuration as + follows: + + .. container:: listingblock + + .. container:: content + + .. code:: + + "engineServiceParameters":{ + "engineParameters":{ + "contextParameters":{ + "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters", + "schemaParameters":{ + "Json":{ + "parameterClassName" : + "org.onap.policy.apex.plugins.context.schema.json.JsonSchemaHelperParameters" + } + } + } + } + } + The AVRO schema handler is added to the configuration as follows: @@ -2203,7 +2264,7 @@ Standard Input .. container:: content - :: + :: "carrierTechnologyParameters" : { "carrierTechnology" : "FILE", (1) @@ -2501,6 +2562,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", + "" + ] + ] } } @@ -2527,6 +2618,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 ============ @@ -2559,35 +2657,72 @@ 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 -####### +###### .. container:: paragraph @@ -2731,7 +2866,7 @@ JMS Output with Object parameter to ``true``. Websocket (WS) IO -######################## +################# .. container:: paragraph @@ -3160,7 +3295,7 @@ REST Server Stand-alone in Servlet REST Requestor IO -################## +################# .. container:: paragraph @@ -3797,7 +3932,6 @@ A configuration example "id" : 45, "instanceCount" : 4, "deploymentPort" : 12345, - "policyModelFileName" : "examples/models/some-model.json", "engineParameters" : { "executorParameters" : { "JAVASCRIPT" : { @@ -4016,12 +4150,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 @@ -4031,12 +4162,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 ------------------- @@ -4239,7 +4367,7 @@ The APEX CLI Tosca Editor The APEX Client --------------------- +--------------- .. container:: paragraph @@ -5164,11 +5292,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 @@ -5190,7 +5328,7 @@ Websockets does not support WAMP at the moment. Websocket in Java ------------------ +################# .. container:: paragraph @@ -5204,7 +5342,7 @@ Websocket in Java Netty, … there are also Kafka extensions for Websockets. Websocket Example Code for Websocket clients (FOSS) ---------------------------------------------------- +################################################### .. container:: paragraph @@ -5237,7 +5375,7 @@ Websocket Example Code for Websocket clients (FOSS) example `__ BCP: Websocket Configuration ----------------------------- +############################ .. container:: paragraph @@ -5270,7 +5408,7 @@ BCP: Websocket Configuration reconnected manually after an APEX boot. Demo with VPN Policy Model --------------------------- +########################## .. container:: paragraph @@ -5297,7 +5435,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 @@ -5364,7 +5502,7 @@ A Websocket Configuration for the VPN Domain } Start APEX Engine -################# +^^^^^^^^^^^^^^^^^ .. container:: paragraph @@ -5378,7 +5516,7 @@ Start APEX Engine .. code:: :number-lines: - #: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json + #: $APEX_HOME/bin/apexApps.sh engine -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json .. container:: listingblock @@ -5387,7 +5525,7 @@ Start APEX Engine .. code:: :number-lines: - #: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json + #: %APEX_HOME%\bin\apexApps.bat engine -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json .. container:: paragraph @@ -5415,7 +5553,7 @@ Start APEX Engine policy is triggered/executed. Run the Websocket Echo Client -############################# +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. container:: paragraph @@ -5505,7 +5643,7 @@ Run the Websocket Echo Client ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake) Run the Websocket Console Client -################################ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. container:: paragraph @@ -5596,7 +5734,7 @@ Run the Websocket Console Client ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake) Send Events -########### +^^^^^^^^^^^ .. container:: paragraph @@ -5736,12 +5874,3 @@ Send Events (APEX). This will also terminate the echo-client in Terminal 2. Then type ``exit`` in Terminal 3 (or ``CTRL+C``) to terminate the console-client. - -.. container:: - :name: footer - - .. container:: - :name: footer-text - - -