X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fdevelopment%2Fdevtools%2Fdevtools.rst;h=0ea25d091bd5a9ac410dfb164c9fd483084f5e91;hb=2154ace6b9d58100212fc5db917d60eb7f69a7a6;hp=5dc3af33a95247925cd3e04b5e64359d0f801c2f;hpb=a38f506800bdfb0c960072f08571ce84c95c66ff;p=policy%2Fparent.git diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst index 5dc3af33..0ea25d09 100644 --- a/docs/development/devtools/devtools.rst +++ b/docs/development/devtools/devtools.rst @@ -11,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: @@ -20,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 @@ -168,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 @@ -204,8 +213,9 @@ Building ONAP Policy Framework Components **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. @@ -246,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 ++++++++++++++++++++++++++++++++++++++++++++++ @@ -264,6 +277,22 @@ 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 *********************** @@ -273,27 +302,17 @@ familiar with the Policy Framework components and test any local changes. .. toctree:: :maxdepth: 1 - policy-gui-controlloop-smoke.rst + policy-gui-acm-smoke.rst db-migrator-smoke.rst - cl-participants-smoke.rst - clamp-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 @@ -304,15 +323,17 @@ 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 - api-s3p.rst - pap-s3p.rst - apex-s3p.rst - drools-s3p.rst - xacml-s3p.rst - distribution-s3p.rst - clamp-s3p.rst Running the Pairwise Tests ************************** @@ -327,6 +348,10 @@ the Policy Framework works in a full ONAP deployment. clamp-dcae.rst + policy-cds.rst + + clamp-sdc.rst + .. api-pairwise.rst @@ -346,54 +371,69 @@ the Policy Framework works in a full ONAP deployment. distribution-pairwise.rst -Generating Swagger Documentation -******************************** -The `Policy Parent Integration POM `_ contains a *generateSwaggerDocs* profile. This -profile can be activated on any module that has a Swagger endopint. When active, this profile creates a tarball in Nexus with the name -*-swagger-docs.tar.gz*. The tarball contains the fillowing files: +Testing OpenSuse docker images +****************************** -.. code-block:: bash +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. - swagger/swagger.html - swagger/swagger.json - swagger/swagger.pdf +1. Build the OpenSuse image you want by running Maven with -Pdockersuse: -The profile is activated when: + .. code-block:: bash + + cd policy/apex-pdp + mvn clean install -Pdockersuse + + The image onap/policy-apex-pdp:latest will be produced. -1. The following property is defined at the top of the *pom.xml* file for a module +2. To avoid ambiguity, tag the image as opensuse: .. code-block:: bash - - post-integration-test + docker tag onap/policy-apex-pdp:latest onap/policy-apex-pdp:opensuse - See the `CLAMP runtime POM `_ for an example of the usage of this property. +3. Clone policy/docker repo. -2. Unit tests are being executed in the build, in other wirds when the *skipTests* flag is *false*. +4. Modify docker/csit/docker-compose.yml to use the tagged OpenSuse image. -You **must** create a unit test in your module that generates the following file: + Replace: -.. code-block:: bash + .. code-block:: yaml - src/test/resources/swagger/swagger.json + apex-pdp: + image: nexus3.onap.org:10001/onap/policy-apex-pdp:${POLICY_APEX_PDP_VERSION} -Typically, you do this by starting your REST endpoint in a unit test, issuing a REST call to get the Swagger API documentation. The test case below is an example -of such a test case. + with: -.. code-block:: java + .. code-block:: yaml - @Test - public void testSwaggerJson() throws Exception { - ResponseEntity httpsEntity = getRestTemplate() - .getForEntity("https://localhost:" + this.httpsPort + "/restservices/clds/api-doc", String.class); - assertThat(httpsEntity.getStatusCode()).isEqualTo(HttpStatus.OK); - assertThat(httpsEntity.getBody()).contains("swagger"); - FileUtils.writeStringToFile(new File("target/swagger/swagger.json"), httpsEntity.getBody(), - Charset.defaultCharset()); - } + 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. + + +Generating Swagger Documentation +******************************** + +1. Accessing Swagger documentation for springboot based policy applications ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -See `this unit test case `_ -for the full example. +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 ********************************************** @@ -420,7 +460,7 @@ Running in Eclipse 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 arument in the run configuration in eclipse: +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 @@ -439,3 +479,15 @@ You may specify a local configuration file instead of *src/test/resources/simPar } ] } + +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 + + strimzi-policy.rst