diff options
Diffstat (limited to 'docs/Distribution-User-Manual.rst')
| -rw-r--r-- | docs/Distribution-User-Manual.rst | 648 |
1 files changed, 0 insertions, 648 deletions
diff --git a/docs/Distribution-User-Manual.rst b/docs/Distribution-User-Manual.rst deleted file mode 100644 index 12f75b9a..00000000 --- a/docs/Distribution-User-Manual.rst +++ /dev/null @@ -1,648 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -Distribution User Manual -************************ - -.. contents:: - :depth: 3 - -Installation -^^^^^^^^^^^^ - -Requirements ------------- - - .. container:: paragraph - - Distribution is 100% written in Java and runs on any platform - that supports a JVM, e.g. Windows, Unix, Cygwin. - -Installation Requirements -######################### - - .. container:: ulist - - - Downloaded distribution: JAVA runtime environment - (JRE, Java 8 or later, Distribution is tested with the - OpenJDK) - - - Building from source: JAVA development kit (JDK, - Java 8 or later, Distribution is tested with the OpenJDK) - - - Sufficient rights to install Distribution on the system - - - Installation tools - - .. container:: ulist - - - TAR and GZ to extract from that TAR.GZ - distribution - - .. container:: ulist - - - Windows for instance - `7Zip <http://www.7-zip.org/>`__ - - - `Docker <https://www.docker.com/>`__ to run Distribution - inside a Docker container - - -Build (Install from Source) Requirements -######################################## - - .. container:: paragraph - - Installation from source requires a few development - tools - - .. container:: ulist - - - GIT to retrieve the source code - - - Java SDK, Java version 8 or later - - - Apache Maven 3 (the Distribution build environment) - -Get the Distribution Source Code --------------------------------- - - .. container:: paragraph - - The Distribution source code is hosted in ONAP as project distribution. - The current stable version is in the master branch. - Simply clone the master branch from ONAP using HTTPS. - - .. container:: listingblock - - .. container:: content - - .. code:: text - - git clone https://gerrit.onap.org/r/policy/distribution - -Build Distribution ------------------- - - .. container:: paragraph - - The examples in this document assume that the distribution source - repositories are cloned to: - - .. container:: ulist - - - Unix, Cygwin: ``/usr/local/src/distribution`` - - - Windows: ``C:\dev\distribution`` - - - Cygwin: ``/cygdrive/c/dev/distribution`` - - .. important:: - A Build requires ONAP Nexus - Distribution has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current - settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__. - - .. important:: - A Build needs Space - Building distribution requires approximately 1-2 GB of hard disc space, 100 MB for the actual build with full - distribution and around 1 GB for the downloaded dependencies. - - .. important:: - A Build requires Internet (for first build) - During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven - repository. The first standard build (and any first specific build) requires Internet access to download those - dependencies. - - .. container:: paragraph - - Use Maven for a standard build without any tests. - - +-------------------------------------------------------+--------------------------------------------------------+ - | Unix, Cygwin | Windows | - +=======================================================+========================================================+ - | .. container:: | .. container:: | - | | | - | .. container:: content | .. container:: content | - | | | - | .. code:: text | .. code:: text | - | | | - | # cd /usr/local/src/distribution | >c: | - | # mvn clean install -DskipTest | >cd \dev\distribution | - | | >mvn clean install -DskipTests | - +-------------------------------------------------------+--------------------------------------------------------+ - -.. container:: paragraph - - The build takes 2-3 minutes on a standard development laptop. It - should run through without errors, but with a lot of messages from - the build process. - -| - -.. container:: paragraph - - When Maven is finished with the build, the final screen should look - similar to this (omitting some ``success`` lines): - -.. container:: listingblock - - .. container:: content - - .. code:: text - - [INFO] ------------------------------------------------------------------------ - [INFO] Reactor Summary: - [INFO] - [INFO] policy-distribution ................................ SUCCESS [ 3.666 s] - [INFO] distribution-model ................................. SUCCESS [ 11.234 s] - [INFO] forwarding ......................................... SUCCESS [ 7.611 s] - [INFO] reception .......................................... SUCCESS [ 7.072 s] - [INFO] main ............................................... SUCCESS [ 21.017 s] - [INFO] plugins ............................................ SUCCESS [ 0.453 s] - [INFO] forwarding-plugins ................................. SUCCESS [01:20 min] - [INFO] reception-plugins .................................. SUCCESS [ 18.545 s] - [INFO] Policy Distribution Packages ....................... SUCCESS [ 0.419 s] - [INFO] ------------------------------------------------------------------------ - [INFO] BUILD SUCCESS - [INFO] ------------------------------------------------------------------------ - [INFO] Total time: 02:39 min - [INFO] Finished at: 2018-11-15T13:59:09Z - [INFO] Final Memory: 73M/1207M - [INFO] ------------------------------------------------------------------------ - -.. container:: paragraph - - The build will have created all artifacts required for distribution - 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:: text | -| | -| -rw-r--r-- 1 user 1049089 10616 Oct 31 13:35 checkstyle-checker.xml | -| -rw-r--r-- 1 user 1049089 609 Oct 31 13:35 checkstyle-header.txt | -| -rw-r--r-- 1 user 1049089 245 Oct 31 13:35 checkstyle-result.xml | -| -rw-r--r-- 1 user 1049089 89 Oct 31 13:35 checkstyle-cachefile | -| drwxr-xr-x 1 user 1049089 0 Oct 31 13:35 maven-archiver/ | -| -rw-r--r-- 1 user 1049089 7171 Oct 31 13:35 policy-distribution-tarball-2.0.1-SNAPSHOT.jar | -| drwxr-xr-x 1 user 1049089 0 Oct 31 13:35 archive-tmp/ | -| -rw-r--r-- 1 user 1049089 66296012 Oct 31 13:35 policy-distribution-tarball-2.0.1-SNAPSHOT-tarball.tar.gz | -| drwxr-xr-x 1 user 1049089 0 Nov 12 10:56 test-classes/ | -| drwxr-xr-x 1 user 1049089 0 Nov 20 14:31 classes/ | -+----------------------------------------------------------------------------------------------------------------------------+ - -+-------------------------------------------------------------------------------------------------------------------+ -| Windows | -+===================================================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. container:: content | -| | -| .. code:: text | -| | -| 11/12/2018 10:56 AM <DIR> . | -| 11/12/2018 10:56 AM <DIR> .. | -| 10/31/2018 01:35 PM <DIR> archive-tmp | -| 10/31/2018 01:35 PM 89 checkstyle-cachefile | -| 10/31/2018 01:35 PM 10,616 checkstyle-checker.xml | -| 10/31/2018 01:35 PM 609 checkstyle-header.txt | -| 10/31/2018 01:35 PM 245 checkstyle-result.xml | -| 11/20/2018 02:31 PM <DIR> classes | -| 10/31/2018 01:35 PM <DIR> maven-archiver | -| 10/31/2018 01:35 PM 66,296,012 policy-distribution-tarball-2.0.1-SNAPSHOT-tarball.tar.gz | -| 10/31/2018 01:35 PM 7,171 policy-distribution-tarball-2.0.1-SNAPSHOT.jar | -| 11/12/2018 10:56 AM <DIR> test-classes | -+-------------------------------------------------------------------------------------------------------------------+ - -Install Distribution --------------------- - - .. container:: paragraph - - Distribution can be installed in different ways: - - .. container:: ulist - - - Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive - - - Windows, Unix, Cygwin: build from source using Maven, then - install manually - -Install Manually from Archive (Windows, 7Zip, GUI) -################################################## - - .. container:: paragraph - - Download a ``tar.gz`` archive and copy the file into the install - folder (in this example ``C:\distribution``). Assuming you are using 7Zip, - right click on the file and extract the ``tar`` archive. - -| - - .. container:: content - - Extract the TAR archive - - .. container:: paragraph - - The right-click on the new created TAR file and extract the actual - distribution. - -| - - .. container:: content - - Extract the distribution - - .. container:: paragraph - - Inside the new distribution folder you see the main directories: ``bin``, - ``etc``and ``lib`` - -| - - .. container:: paragraph - - Once extracted, please rename the created folder to - ``distribution-full-2.0.2-SNAPSHOT``. This will keep the directory name in - line with the rest of this documentation. - -Build from Source ------------------ - -Build and Install Manually (Unix, Windows, Cygwin) -################################################## - - .. container:: paragraph - - Clone the Distribution GIT repositories into a directory. Go to that - directory. Use Maven to build Distribution (all details on building - Distribution from source can be found in *Distribution HowTo: Build*). - - .. container:: paragraph - - Now, take the ``.tar.gz`` file and install distribution. - -Installation Layout -------------------- - - .. container:: paragraph - - A full installation of distribution comes with the following layout. - - .. container:: listingblock - - .. container:: content - - - bin - - etc - - lib - -Running Distribution in Docker ------------------------------- - -Run in ONAP -########### - - .. container:: paragraph - - Running distribution from the ONAP docker repository only requires 2 - commands: - - .. container:: olist arabic - - #. Log into the ONAP docker repo - - .. container:: listingblock - - .. container:: content - - :: - - docker login -u docker -p docker nexus3.onap.org:10003 - - .. container:: olist arabic - - #. Run the distribution docker image - - .. container:: listingblock - - .. container:: content - - :: - - docker run -it --rm nexus3.onap.org:10003/onap/policy-distribution:latest - -Build a Docker Image -#################### - - .. container:: paragraph - - Alternatively, one can use the Dockerfile defined in the Docker - package to build an image. - -Distribution Configurations Explained -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Introduction to Distribution Configuration ------------------------------------------- - - .. container:: paragraph - - A distribution engine can be configured to use various combinations - of policy reception handlers, policy decoders and policy forwarders. - The system is build using a plugin architecture. Each configuration - option is realized by a plugin, which can be loaded and - configured when the engine is started. New plugins can be - added to the system at any time, though to benefit from a - new plugin an engine will need to be restarted. - - | - - .. container:: paragraph - - The distribution already comes with sdc reception handler, - file reception handler, xacml policy decoder, file in csar policy decoder, - xacml policy forwarder, apex policy forwarder. - -General Configuration Format ----------------------------- - - .. container:: paragraph - - The distribution configuration file is a JSON file containing a few - main blocks for different parts of the configuration. Each - block then holds the configuration details. The following - code shows the main blocks: - - .. container:: listingblock - - .. container:: content - - .. code:: text - - { - "restServerParameters":{ - ... (1) - }, - "receptionHandlerParameters":{ (2) - "pluginHandlerParameters":{ (3) - "policyDecoders":{...}, (4) - "policyForwarders":{...} (5) - } - }, - "receptionHandlerConfigurationParameters":{ - ... (6) - } - , - "policyForwarderConfigurationParameters":{ - ... (7) - } - , - "policyDecoderConfigurationParameters":{ - ... (8) - } - } - - .. container:: colist arabic - - +-----------------------------------+-----------------------------------+ - | **1** | rest server configuration | - +-----------------------------------+-----------------------------------+ - | **2** | reception handler plugin | - | | configurations | - +-----------------------------------+-----------------------------------+ - | **3** | plugin handler parameters | - | | configuration | - +-----------------------------------+-----------------------------------+ - | **4** | policy decoder plugin | - | | configuration | - +-----------------------------------+-----------------------------------+ - | **5** | policy forwarder plugin | - | | configuration | - +-----------------------------------+-----------------------------------+ - | **6** | reception handler plugin | - | | parameters | - +-----------------------------------+-----------------------------------+ - | **7** | policy forwarder plugin | - | | parameters | - +-----------------------------------+-----------------------------------+ - | **8** | policy decoder plugin | - | | parameters | - +-----------------------------------+-----------------------------------+ - -A configuration example ------------------------ - - .. container:: paragraph - - The following example loads HPA use case related plug-ins. - - .. container:: paragraph - - Notifications are consumed from SDC through SDC client. - Consumed artifacts format is CSAR. - - .. container:: paragraph - - Generated policies are forwarded to XACML policy engine. - - .. container:: listingblock - - .. container:: content - - .. code:: text - - { - "name":"SDCDistributionGroup", - "restServerParameters":{ - "host":"0.0.0.0", - "port":6969, - "userName":"healthcheck", - "password":"zb!XztG34" - }, - "receptionHandlerParameters":{ - "SDCReceptionHandler":{ - "receptionHandlerType":"SDC", - "receptionHandlerClassName":"org.onap.policy.distribution.reception.handling.sdc.SdcReceptionHandler", - "receptionHandlerConfigurationName":"sdcConfiguration", - "pluginHandlerParameters":{ - "policyDecoders":{ - "CsarDecoder":{ - "decoderType":"CsarDecoder", - "decoderClassName":"org.onap.policy.distribution.reception.decoding.pdpx.PolicyDecoderCsarPdpx", - "decoderConfigurationName": "csarToOptimizationPolicyConfiguration" - } - }, - "policyForwarders":{ - "PAPEngineForwarder":{ - "forwarderType":"PAPEngine", - "forwarderClassName":"org.onap.policy.distribution.forwarding.xacml.pdp.XacmlPdpPolicyForwarder", - "forwarderConfigurationName": "xacmlPdpConfiguration" - } - } - } - } - }, - "receptionHandlerConfigurationParameters":{ - "sdcConfiguration":{ - "parameterClassName":"org.onap.policy.distribution.reception.handling.sdc.SdcReceptionHandlerConfigurationParameterGroup", - "parameters":{ - "asdcAddress": "sdc-be.onap:8443", - "messageBusAddress": [ - "message-router.onap" - ], - "user": "policy", - "password": "Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U", - "pollingInterval":20, - "pollingTimeout":30, - "consumerId": "policy-id", - "artifactTypes": [ - "TOSCA_CSAR", - "HEAT" - ], - "consumerGroup": "policy-group", - "environmentName": "AUTO", - "keystorePath": "null", - "keystorePassword": "null", - "activeserverTlsAuth": false, - "isFilterinEmptyResources": true, - "isUseHttpsWithDmaap": false - } - } - }, - "policyDecoderConfigurationParameters":{ - "csarToOptimizationPolicyConfiguration":{ - "parameterClassName":"org.onap.policy.distribution.reception.decoding.pdpx.PolicyDecoderCsarPdpxConfigurationParameterGroup", - "parameters":{ - "policyNamePrefix": "oofCasablanca", - "onapName": "OOF", - "version": "1.0", - "priority": "3", - "riskType": "Test", - "riskLevel": "2" - } - } - }, - "policyForwarderConfigurationParameters":{ - "xacmlPdpConfiguration":{ - "parameterClassName":"org.onap.policy.distribution.forwarding.xacml.pdp.XacmlPdpPolicyForwarderParameterGroup", - "parameters":{ - "useHttps": false, - "hostname": "pdp", - "port": 8081, - "userName": "testpdp", - "password": "alpha123", - "clientAuth": "cHl0aG9uOnRlc3Q=", - "isManaged": true, - "pdpGroup": "pdpGroup" - } - } - } - } - - -The Distribution Engine -^^^^^^^^^^^^^^^^^^^^^^^ - - .. container:: paragraph - - The Distribution engine can be started using ``policy-dist.sh`` script. - The script is located in the source code at - *distribution/packages/policy-distribution-docker/src/main/docker* - directory - - | - - .. container:: paragraph - - On UNIX and Cygwin systems use ``policy-dist.sh`` script. - - | - - .. container:: paragraph - - On Windows systems navigate to the distribution installation directory. - Run the following command - ``java -cp "etc:lib\*" org.onap.policy.distribution.main.startstop.Main -c <config-file-path>`` - - | - - .. container:: paragraph - - The Distribution engine comes with CLI arguments for setting - configuration. The configuration file is always required. - The option ``-h`` prints a help screen. - - .. container:: listingblock - - .. container:: content - - .. code:: text - - usage: org.onap.policy.distribution.main.startstop.Main [options...] - options - -c,--config-file <CONFIG_FILE> the full path to the configuration file to use, the configuration file must be a Json file - containing the distribution configuration parameters - -h,--help outputs the usage of this command - -v,--version outputs the version of distribution system - - -The Distribution REST End-points -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. container:: paragraph - - The distribution engine comes with built-in REST based - endpoints for fetching health check status & statistical data - of running distribution system. - - .. container:: listingblock - - .. container:: content - - .. code:: text - - # Example Output from curl http -a '{user}:{password}' :6969/healthcheck - - HTTP/1.1 200 OK - Content-Length: XXX - Content-Type: application/json - Date: Tue, 17 Apr 2018 10:51:14 GMT - Server: Jetty(9.3.20.v20170531) - { - "code":200, - "healthy":true, - "message":"alive", - "name":"Policy SSD", - "url":"self" - } - - # Example Output from curl http -a '{user}:{password}' :6969/statistics - - HTTP/1.1 200 OK - Content-Length: XXX - Content-Type: application/json - Date: Tue, 17 Apr 2018 10:51:14 GMT - Server: Jetty(9.3.20.v20170531) - { - "code":200, - "distributions":10, - "distribution_complete_ok":8, - "distribution_complete_fail":2, - "downloads":15, - "downloads_ok"; 10, - "downloads_error": 5 - } - |