+++ /dev/null
-.. 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
- }
-
Code Review / policy / distribution.git / commitdiff