: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:
* 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 <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_ (bottom of the linked page)
+* You have added settings to access the ONAP Nexus to your M2 configuration,
+ see `Maven Settings Example <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_
+ (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 <https://gerrit.onap.org/r/#/admin/projects/?filter=policy>`_. 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 <https://gerrit.onap.org/r/admin/repos/q/filter:policy>`_.
+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
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
**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.
`Example Compose Script to run MariaDB <https://gerrit.onap.org/r/gitweb?p=integration/csit.git;a=blob;f=scripts/policy/docker-compose-api.yml;h=e32190f1e6cb6d9b64ddf53a2db2c746723a0c6a;hb=refs/heads/master>`_
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 <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=blob;f=packages/policy-api-tarball/src/main/resources/etc/defaultConfig.json;h=042fb9d54c79ce4dad517e2564636632a8ecc550;hb=refs/heads/master>`_
+`Default Policy API Configuration <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=blob;f=packages/policy-api-tarball/src/main/resources/etc/apiParameters.yaml;h=2c19199a8a889cb0ab203334182662fe15e1635e;hb=refs/heads/master>`_
-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
++++++++++++++++++++++++++++++++++++++++++++++
`Policy CSIT API Docker Compose <https://gerrit.onap.org/r/gitweb?p=integration/csit.git;a=blob;f=scripts/policy/docker-compose-api.yml;h=e32190f1e6cb6d9b64ddf53a2db2c746723a0c6a;hb=refs/heads/master>`_
+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 <https://gerrit.onap.org/r/gitweb?p=policy/pap.git;a=blob;f=packages/policy-pap-tarball/src/main/resources/etc/papParameters.yaml;h=06dd45f4946fd0a11ed8ef859f8fc5bcf409a3f0;hb=HEAD>`_
+
+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
***********************
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
- distribution-smoke.rst
-
-..
drools-smoke.rst
-
-..
xacml-smoke.rst
-
-..
distribution-smoke.rst
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
**************************
policy-cds.rst
+ clamp-sdc.rst
+
..
api-pairwise.rst
distribution-pairwise.rst
-Generating Swagger Documentation
-********************************
-The `Policy Parent Integration POM <https://github.com/onap/policy-parent/blob/master/integration/pom.xml>`_ 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
-*<project-artifactId>-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.
+
+1. Build the OpenSuse image you want by running Maven with -Pdockersuse:
+
+ .. code-block:: bash
- swagger/swagger.html
- swagger/swagger.json
- swagger/swagger.pdf
+ cd policy/apex-pdp
+ mvn clean install -Pdockersuse
-The profile is activated when:
+ 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
- <!-- This property triggers generation of the Swagger documents -->
- <swagger.generation.phase>post-integration-test</swagger.generation.phase>
+ docker tag onap/policy-apex-pdp:latest onap/policy-apex-pdp:opensuse
- See the `CLAMP runtime POM <https://github.com/onap/policy-clamp/blob/master/runtime/pom.xml>`_ 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<String> 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
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Springfox Swagger2 maven dependency aids with auto-generation of Swagger documentation.
-See `this unit test case <https://github.com/onap/policy-clamp/blob/master/runtime/src/test/java/org/onap/policy/clamp/clds/it/HttpsItCase.java>`_
-for the full example.
+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
**********************************************
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
}
]
}
+
+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