X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fdevelopment%2Fdevtools%2Fdevtools.rst;h=1bb96a8db42652b0d1df13eaf4020322f5ceb9e4;hb=f4e2d245485f4a55185d3ef52060b136a25aff6a;hp=9646ffa963738f81a588dc56ed60261aef678ffb;hpb=ba45dc60c7ab209b693c9cf53982e177b2fbb70e;p=policy%2Fparent.git diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst index 9646ffa9..1bb96a8d 100644 --- a/docs/development/devtools/devtools.rst +++ b/docs/development/devtools/devtools.rst @@ -2,6 +2,7 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _policy-development-tools-label: Policy Platform Development Tools ################################# @@ -10,8 +11,10 @@ Policy Platform Development Tools :depth: 3 -This article explains how to build the ONAP Policy Framework for development purposes and how to run stability/performance tests for a variety of components. To start, the developer should consult the latest ONAP Wiki to familiarize themselves with developer best practices and how-tos to setup their environment, see `https://wiki.onap.org/display/DW/Developer+Best+Practices`. - +This article explains how to build the ONAP Policy Framework for development purposes and how to run stability/ +performance tests for a variety of components. To start, the developer should consult the latest ONAP Wiki to +familiarize themselves with developer best practices and how-tos to setup their environment, +see `https://wiki.onap.org/display/DW/Developer+Best+Practices`. This article assumes that: @@ -19,16 +22,22 @@ This article assumes that: * You are using a directory called *git* off your home directory *(~/git)* for your git repositories * Your local maven repository is in the location *~/.m2/repository* * You have copied the settings.xml from oparent to *~/.m2/* directory -* You have added settings to access the ONAP Nexus to your M2 configuration, see `Maven Settings Example `_ (bottom of the linked page) +* You have added settings to access the ONAP Nexus to your M2 configuration, + see `Maven Settings Example `_ + (bottom of the linked page) -The procedure documented in this article has been verified to work on a MacBook laptop running macOS Mojave Version 10.14.6 and an Unbuntu 18.06 VM. +The procedure documented in this article has been verified to work on a MacBook laptop running macOS Mojave Version +10.14.6 and an Ubuntu 18.06 VM. Cloning All The Policy Repositories *********************************** -Run a script such as the script below to clone the required modules from the `ONAP git repository `_. This script clones all the ONAP Policy Framework repositories. +Run a script such as the script below to clone the required modules from the +`ONAP git repository `_. +This script clones all the ONAP Policy Framework repositories. -ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module, and the A&AI Schema module. +ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module, +and the A&AI Schema module. .. code-block:: bash @@ -57,7 +66,7 @@ ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the policy/xacml-pdp \ policy/distribution \ policy/gui \ - policy/engine " + policy/clamp " ## ## Help screen and exit condition (i.e. too few arguments) @@ -151,7 +160,7 @@ Execution of the script above results in the following directory hierarchy in yo * ~/git/onap/policy/docker * ~/git/onap/policy/drools-applications * ~/git/onap/policy/drools-pdp - * ~/git/onap/policy/engine + * ~/git/onap/policy/clamp * ~/git/onap/policy/apex-pdp * ~/git/onap/policy/xacml-pdp * ~/git/onap/policy/distribution @@ -167,7 +176,8 @@ Building ONAP Policy Framework Components rm -fr ~/.m2/repository/org/onap -**Step 2:** A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* file in the directory *~/git/onap/policy*. +**Step 2:** A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* +file in the directory *~/git/onap/policy*. .. code-block:: xml :caption: Typical pom.xml to build the ONAP Policy Framework @@ -197,17 +207,15 @@ Building ONAP Policy Framework Components drools-applications distribution gui - - engine + clamp **Policy Architecture/API Transition** -In Dublin, a new Policy Architecture was introduced. The legacy architecture runs in parallel with the new architecture. It will be deprecated after Frankfurt release. -If the developer is only interested in working with the new architecture components, the engine sub-module can be ommitted. +In Dublin, a new Policy Architecture was introduced. The legacy architecture runs in parallel with the new +architecture. It will be deprecated after Frankfurt release. If the developer is only interested in working with the +new architecture components, the engine sub-module can be ommitted. **Step 3:** You can now build the Policy framework. @@ -232,7 +240,7 @@ Developing and Debugging each Policy Component Running a MariaDb Instance ++++++++++++++++++++++++++ -The Policy Framework requires a MariaDb instance running. The easiest way to do this is to run a docker image locally. +The Policy Framework requires a MariaDb instance running. The easiest way to do this is to run a docker image locally. One example on how to do this is to use the scripts used by the policy/api S3P tests. @@ -248,16 +256,19 @@ Another example on how to run the MariaDb is using the docker compose file used `Example Compose Script to run MariaDB `_ Running the API component standalone -+++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++ -Assuming you have successfully built the codebase using the instructions above. The only requirement for the API component to run is a -running MariaDb database instance. The easiest way to do this is to run the docker image, please see the mariadb documentation for the latest -information on doing so. Once the mariadb is up and running, a configuration file must be provided to the api in order for it to know how to -connect to the mariadb. You can locate the default configuration file in the packaging of the api component: +Assuming you have successfully built the codebase using the instructions above. The only requirement for the API +component to run is a running MariaDb database instance. The easiest way to do this is to run the docker image, please +see the mariadb documentation for the latest information on doing so. Once the mariadb is up and running, a +configuration file must be provided to the api in order for it to know how to connect to the mariadb. You can locate +the default configuration file in the packaging of the api component: -`Default API Configuration `_ +`Default Policy API Configuration `_ -You will want to change the fields pertaining to "host", "port" and "databaseUrl" to your local environment settings. +You will want to change the fields pertaining to "host", "port" and "databaseUrl" to your local environment settings +and start the policy-api springboot application either using your IDE of choice or using the run goal from Spring Boot +Maven plugin: *mvn spring-boot:run*. Running the API component using Docker Compose ++++++++++++++++++++++++++++++++++++++++++++++ @@ -266,6 +277,45 @@ An example of running the api using a docker compose script is located in the Po `Policy CSIT API Docker Compose `_ +Running the PAP component standalone +++++++++++++++++++++++++++++++++++++ + +Once you have successfully built the PAP codebase, a running MariaDb database and DMaaP instance will also be required +to start up the application. For MariaDb instance, the easiest way is to run the docker image, please see the mariadb +documentation for the latest information on doing so. For DMaaP, the easiest way during development is to run the DMaaP +simulator which is explained in the below sections. Once the mariadb and DMaaP are running, a configuration file must +be provided to the PAP component in order for it to know how to connect to the mariadb and DMaaP along with other +relevant configuration details. You can locate the default configuration file in the packaging of the PAP component: + +`Default PAP Configuration `_ + +Update the fields related to MariaDB, DMaaP and the RestServer for the application as per your local environment settings. +Then to start the application, just run the Spring Boot application using IDE or command line. + + +Running the Smoke Tests +*********************** + +The following links contain instructions on how to run the smoke tests. These may be helpful to developers to become +familiar with the Policy Framework components and test any local changes. + +.. toctree:: + :maxdepth: 1 + + policy-gui-acm-smoke.rst + db-migrator-smoke.rst + smoke/acm-participants-smoke.rst + smoke/clamp-smoke.rst + clamp-cl-participant-protocol-smoke.rst + policy-participant-smoke.rst + api-smoke.rst + pap-smoke.rst + apex-smoke.rst + drools-smoke.rst + xacml-smoke.rst + distribution-smoke.rst + + Running the Stability/Performance Tests *************************************** @@ -273,10 +323,181 @@ The following links contain instructions on how to run the S3P Stability and Per familiar with the Policy Framework components and test any local changes. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + + testing/s3p/run-s3p.rst + testing/s3p/api-s3p.rst + testing/s3p/pap-s3p.rst + testing/s3p/apex-s3p.rst + testing/s3p/drools-s3p.rst + testing/s3p/xacml-s3p.rst + testing/s3p/distribution-s3p.rst + testing/s3p/clamp-s3p.rst + + +Running the Pairwise Tests +************************** + +The following links contain instructions on how to run the pairwise tests. These may be helpful to developers check that +the Policy Framework works in a full ONAP deployment. + +.. toctree:: + :maxdepth: 1 + + clamp-policy.rst + + clamp-dcae.rst + + policy-cds.rst + + clamp-sdc.rst + +.. + api-pairwise.rst + +.. + pap-pairwise.rst + +.. + apex-pairwise.rst + +.. + drools-pairwise.rst + +.. + xacml-pairwise.rst + +.. + distribution-pairwise.rst + + +Testing OpenSuse docker images +****************************** + +Policy Framework offers docker images in two flavors: Alpine and OpenSuse. +Alpine images are used in OOM for ONAP deployments. +The OpenSuse images are built manually if needed, by running Maven with the -Pdockersuse profile. +To test these images, CSITs will be run. + +1. Build the OpenSuse image you want by running Maven with -Pdockersuse: + + .. code-block:: bash + + cd policy/apex-pdp + mvn clean install -Pdockersuse + + The image onap/policy-apex-pdp:latest will be produced. + +2. To avoid ambiguity, tag the image as opensuse: + + .. code-block:: bash + + docker tag onap/policy-apex-pdp:latest onap/policy-apex-pdp:opensuse + +3. Clone policy/docker repo. + +4. Modify docker/csit/docker-compose.yml to use the tagged OpenSuse image. + + Replace: + + .. code-block:: yaml + + apex-pdp: + image: nexus3.onap.org:10001/onap/policy-apex-pdp:${POLICY_APEX_PDP_VERSION} + + with: + + .. code-block:: yaml + + apex-pdp: + image: onap/policy-apex-pdp:opensuse + +5. Run the project CSIT. For apex-pdp: + + .. code-block:: bash + + cd docker/csit + ./run-project-csit.sh apex-pdp + + Automated tests will be run, and log files displayed. + +Running Policy Components Locally +********************************* + +The following page outlines how to run the policy framework components locally use IntelliJ, Eclipse and the Command Line. + +.. toctree:: + :maxdepth: 1 + + local-installation.rst + + +Generating Swagger Documentation +******************************** + +1. Accessing Swagger documentation for springboot based policy applications ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Springfox Swagger2 maven dependency aids with auto-generation of Swagger documentation. + +Using the Swagger-UI maven dependency Swagger HTML documentation can be accessed at the root url. + +- The generated swagger.json can be accessed at: *https://service_IP:service_port/v2/api-docs* +- Swagger UI can be accessed at: *https://service_IP:service_port/swagger-ui/index.html* + +Running the DMaaP Simulator during Development +********************************************** +It is sometimes convenient to run the DMaaP simulator during development. You can run it from the command line using Maven or from within your IDE. + +Running on the Command Line ++++++++++++++++++++++++++++ +1. Check out the policy models repository +2. Go to the *models-sim/policy-models-simulators* subdirectory in the policy-models repo +3. Run the following Maven command: + + .. code-block:: bash + + mvn exec:java -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/simParameters.json" + +Running in Eclipse +++++++++++++++++++ +1. Check out the policy models repository +2. Go to the *models-sim/policy-models-simulators* module in the policy-models repo +3. Specify a run configuration using the class *org.onap.policy.models.simulators.Main* as the main class +4. Specify an argument of *src/test/resources/simParameters.json* to the run configuration +5. Run the configuration + +Specifying a local configuration file ++++++++++++++++++++++++++++++++++++++ + +You may specify a local configuration file instead of *src/test/resources/simParameters.json* on the command line or as an argument in the run configuration in eclipse: + +.. code-block:: json + + { + "dmaapProvider": { + "name": "DMaaP simulator", + "topicSweepSec": 900 + }, + "restServers": [ + { + "name": "DMaaP simulator", + "providerClass": "org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1", + "host": "localhost", + "port": 3904, + "https": false + } + ] + } + +Bringing up Strimzi-Kafka Deploment with Policy Framework +********************************************************* + +This page will explain how to setup a local Kubernetes cluster and minimal helm setup to run and deploy Policy Framework on a single host. + +This is meant for a development purpose only as we are going to use microk8s in this page + +.. toctree:: + :maxdepth: 1 - api-s3p.rst - pap-s3p.rst - apex-s3p.rst - drools-s3p.rst - xacml-s3p.rst + strimzi-policy.rst