docs/development/devtools/devtools.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _policy-development-tools-label:
   6
   7 Policy Platform Development Tools
   8 #################################
   9
  10 .. contents::
  11     :depth: 3
  12
  13
  14 This article explains how to build the ONAP Policy Framework for development purposes and how to run stability/
  15 performance tests for a variety of components. To start, the developer should consult the latest ONAP Wiki to
  16 familiarize themselves with developer best practices and how-tos to setup their environment,
  17 see `https://wiki.onap.org/display/DW/Developer+Best+Practices`.
  18
  19 This article assumes that:
  20
  21 * You are using a *\*nix* operating system such as linux or macOS.
  22 * You are using a directory called *git* off your home directory *(~/git)* for your git repositories
  23 * Your local maven repository is in the location *~/.m2/repository*
  24 * You have copied the settings.xml from oparent to *~/.m2/* directory
  25 * You have added settings to access the ONAP Nexus to your M2 configuration,
  26   see `Maven Settings Example <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_
  27   (bottom of the linked page)
  28
  29 The procedure documented in this article has been verified to work on a MacBook laptop running macOS Mojave Version
  30 10.14.6 and an Ubuntu 18.06 VM.
  31
  32 Cloning All The Policy Repositories
  33 ***********************************
  34
  35 Run a script such as the script below to clone the required modules from the
  36 `ONAP git repository <https://gerrit.onap.org/r/admin/repos/q/filter:policy>`_.
  37 This script clones all the ONAP Policy Framework repositories.
  38
  39 ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module,
  40 and the A&AI Schema module.
  41
  42
  43 .. code-block:: bash
  44    :caption: Typical ONAP Policy Framework Clone Script
  45    :linenos:
  46
  47     #!/usr/bin/env bash
  48
  49     ## script name for output
  50     MOD_SCRIPT_NAME=`basename $0`
  51
  52     ## the ONAP clone directory, defaults to "onap"
  53     clone_dir="onap"
  54
  55     ## the ONAP repos to clone
  56     onap_repos="\
  57     policy/parent \
  58     policy/common \
  59     policy/models \
  60     policy/docker \
  61     policy/api \
  62     policy/pap \
  63     policy/apex-pdp \
  64     policy/drools-pdp \
  65     policy/drools-applications \
  66     policy/xacml-pdp \
  67     policy/distribution \
  68     policy/gui \
  69     policy/clamp "
  70
  71     ##
  72     ## Help screen and exit condition (i.e. too few arguments)
  73     ##
  74     Help()
  75     {
  76         echo ""
  77         echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
  78         echo ""
  79         echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
  80         echo ""
  81         echo "       Options"
  82         echo "         -d          - the ONAP clone directory, defaults to '.'"
  83         echo "         -h          - this help screen"
  84         echo ""
  85         exit 255;
  86     }
  87
  88     ##
  89     ## read command line
  90     ##
  91     while [ $# -gt 0 ]
  92     do
  93         case $1 in
  94             #-d ONAP clone directory
  95             -d)
  96                 shift
  97                 if [ -z "$1" ]; then
  98                     echo "$MOD_SCRIPT_NAME: no clone directory"
  99                     exit 1
 100                 fi
 101                 clone_dir=$1
 102                 shift
 103             ;;
 104
 105             #-h prints help and exists
 106             -h)
 107                 Help;exit 0;;
 108
 109             *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
 110         esac
 111     done
 112
 113     if [ -f "$clone_dir" ]; then
 114         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
 115         exit 2
 116     fi
 117     if [ -d "$clone_dir" ]; then
 118         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
 119         exit 2
 120     fi
 121
 122     mkdir $clone_dir
 123     if [ $? != 0 ]
 124     then
 125         echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
 126         exit 3
 127     fi
 128
 129     for repo in $onap_repos
 130     do
 131         repoDir=`dirname "$repo"`
 132         repoName=`basename "$repo"`
 133
 134         if [ ! -z $dirName ]
 135         then
 136             mkdir "$clone_dir/$repoDir"
 137             if [ $? != 0 ]
 138             then
 139                 echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
 140                 exit 4
 141             fi
 142         fi
 143
 144         git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
 145     done
 146
 147     echo ONAP has been cloned into '"'$clone_dir'"'
 148
 149
 150 Execution of the script above results in the following directory hierarchy in your *~/git* directory:
 151
 152     *  ~/git/onap
 153     *  ~/git/onap/policy
 154     *  ~/git/onap/policy/parent
 155     *  ~/git/onap/policy/common
 156     *  ~/git/onap/policy/models
 157     *  ~/git/onap/policy/api
 158     *  ~/git/onap/policy/pap
 159     *  ~/git/onap/policy/gui
 160     *  ~/git/onap/policy/docker
 161     *  ~/git/onap/policy/drools-applications
 162     *  ~/git/onap/policy/drools-pdp
 163     *  ~/git/onap/policy/clamp
 164     *  ~/git/onap/policy/apex-pdp
 165     *  ~/git/onap/policy/xacml-pdp
 166     *  ~/git/onap/policy/distribution
 167
 168
 169 Building ONAP Policy Framework Components
 170 *****************************************
 171
 172 **Step 1:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
 173
 174     .. code-block:: bash
 175
 176         rm -fr ~/.m2/repository/org/onap
 177
 178
 179 **Step 2:**  A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml*
 180 file in the directory *~/git/onap/policy*.
 181
 182 .. code-block:: xml
 183    :caption: Typical pom.xml to build the ONAP Policy Framework
 184    :linenos:
 185
 186     <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 187         <modelVersion>4.0.0</modelVersion>
 188         <groupId>org.onap</groupId>
 189         <artifactId>onap-policy</artifactId>
 190         <version>1.0.0-SNAPSHOT</version>
 191         <packaging>pom</packaging>
 192         <name>${project.artifactId}</name>
 193         <inceptionYear>2017</inceptionYear>
 194         <organization>
 195             <name>ONAP</name>
 196         </organization>
 197
 198         <modules>
 199             <module>parent</module>
 200             <module>common</module>
 201             <module>models</module>
 202             <module>api</module>
 203             <module>pap</module>
 204             <module>apex-pdp</module>
 205             <module>xacml-pdp</module>
 206             <module>drools-pdp</module>
 207             <module>drools-applications</module>
 208             <module>distribution</module>
 209             <module>gui</module>
 210             <module>clamp</module>
 211         </modules>
 212     </project>
 213
 214 **Policy Architecture/API Transition**
 215
 216 In Dublin, a new Policy Architecture was introduced. The legacy architecture runs in parallel with the new
 217 architecture. It will be deprecated after Frankfurt release. If the developer is only interested in working with the
 218 new architecture components, the engine sub-module can be ommitted.
 219
 220
 221 **Step 3:** You can now build the Policy framework.
 222
 223 Java artifacts only:
 224
 225     .. code-block:: bash
 226
 227        cd ~/git/onap
 228        mvn clean install
 229
 230 With docker images:
 231
 232     .. code-block:: bash
 233
 234        cd ~/git/onap
 235        mvn clean install -P docker
 236
 237 Developing and Debugging each Policy Component
 238 **********************************************
 239
 240 Running a MariaDb Instance
 241 ++++++++++++++++++++++++++
 242
 243 The Policy Framework requires a MariaDb instance running. The easiest way to do this is to run a docker image locally.
 244
 245 One example on how to do this is to use the scripts used by the policy/api S3P tests.
 246
 247 `Simulator Setup Script Example <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=tree;f=testsuites/stability/src/main/resources/simulatorsetup;h=9038413f67cff2e2a79d6345f198f96ee0c57de1;hb=refs/heads/master>`_
 248
 249     .. code-block:: bash
 250
 251        cd ~/git/onap/api/testsuites/stability/src/main/resources/simulatorsetup
 252        ./setup_components.sh
 253
 254 Another example on how to run the MariaDb is using the docker compose file used by the Policy API CSITs:
 255
 256 `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>`_
 257
 258 Running the API component standalone
 259 ++++++++++++++++++++++++++++++++++++
 260
 261 Assuming you have successfully built the codebase using the instructions above. The only requirement for the API
 262 component to run is a running MariaDb database instance. The easiest way to do this is to run the docker image, please
 263 see the mariadb documentation for the latest information on doing so. Once the mariadb is up and running, a
 264 configuration file must be provided to the api in order for it to know how to connect to the mariadb. You can locate
 265 the default configuration file in the packaging of the api component:
 266
 267 `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>`_
 268
 269 You will want to change the fields pertaining to "host", "port" and "databaseUrl" to your local environment settings
 270 and start the policy-api springboot application either using your IDE of choice or using the run goal from Spring Boot
 271 Maven plugin: *mvn spring-boot:run*.
 272
 273 Running the API component using Docker Compose
 274 ++++++++++++++++++++++++++++++++++++++++++++++
 275
 276 An example of running the api using a docker compose script is located in the Policy Integration CSIT test repository.
 277
 278 `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>`_
 279
 280 Running the PAP component standalone
 281 ++++++++++++++++++++++++++++++++++++
 282
 283 Once you have successfully built the PAP codebase, a running MariaDb database and DMaaP instance will also be required
 284 to start up the application. For MariaDb instance, the easiest way is to run the docker image, please see the mariadb
 285 documentation for the latest information on doing so. For DMaaP, the easiest way during development is to run the DMaaP
 286 simulator which is explained in the below sections. Once the mariadb and DMaaP are running, a configuration file must
 287 be provided to the PAP component in order for it to know how to connect to the mariadb and DMaaP along with other
 288 relevant configuration details. You can locate the default configuration file in the packaging of the PAP component:
 289
 290 `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>`_
 291
 292 Update the fields related to MariaDB, DMaaP and the RestServer for the application as per your local environment settings.
 293 Then to start the application, just run the Spring Boot application using IDE or command line.
 294
 295
 296 Running the Smoke Tests
 297 ***********************
 298
 299 The following links contain instructions on how to run the smoke tests. These may be helpful to developers to become
 300 familiar with the Policy Framework components and test any local changes.
 301
 302 .. toctree::
 303    :maxdepth: 1
 304
 305    smoke/policy-gui-acm-smoke.rst
 306    smoke/db-migrator-smoke.rst
 307    smoke/acm-participants-smoke.rst
 308    smoke/clamp-smoke.rst
 309    smoke/clamp-ac-participant-protocol-smoke.rst
 310    smoke/policy-participant-smoke.rst
 311    smoke/api-smoke.rst
 312    smoke/pap-smoke.rst
 313    smoke/apex-smoke.rst
 314    smoke/drools-smoke.rst
 315    smoke/xacml-smoke.rst
 316    smoke/distribution-smoke.rst
 317
 318
 319 Running the Stability/Performance Tests
 320 ***************************************
 321
 322 The following links contain instructions on how to run the S3P Stability and Performance tests. These may be helpful to developers to become
 323 familiar with the Policy Framework components and test any local changes.
 324
 325 .. toctree::
 326    :maxdepth: 2
 327
 328    testing/s3p/run-s3p.rst
 329    testing/s3p/api-s3p.rst
 330    testing/s3p/pap-s3p.rst
 331    testing/s3p/apex-s3p.rst
 332    testing/s3p/drools-s3p.rst
 333    testing/s3p/xacml-s3p.rst
 334    testing/s3p/distribution-s3p.rst
 335    testing/s3p/clamp-s3p.rst
 336
 337
 338 Running the Pairwise Tests
 339 **************************
 340
 341 The following links contain instructions on how to run the pairwise tests. These may be helpful to developers check that
 342 the Policy Framework works in a full ONAP deployment.
 343
 344 .. toctree::
 345    :maxdepth: 1
 346
 347    pairwise/clamp-policy.rst
 348    pairwise/clamp-dcae.rst
 349    pairwise/policy-cds.rst
 350    pairwise/clamp-sdc.rst
 351
 352 ..
 353    api-pairwise.rst
 354
 355 ..
 356    pap-pairwise.rst
 357
 358 ..
 359    apex-pairwise.rst
 360
 361 ..
 362    drools-pairwise.rst
 363
 364 ..
 365    xacml-pairwise.rst
 366
 367 ..
 368    distribution-pairwise.rst
 369
 370
 371 Testing OpenSuse docker images
 372 ******************************
 373
 374 Policy Framework offers docker images in two flavors: Alpine and OpenSuse.
 375 Alpine images are used in OOM for ONAP deployments.
 376 The OpenSuse images are built manually if needed, by running Maven with the -Pdockersuse profile.
 377 To test these images, CSITs will be run.
 378
 379 1. Build the OpenSuse image you want by running Maven with -Pdockersuse:
 380
 381     .. code-block:: bash
 382
 383         cd policy/apex-pdp
 384         mvn clean install -Pdockersuse
 385
 386     The image onap/policy-apex-pdp:latest will be produced.
 387
 388 2. To avoid ambiguity, tag the image as opensuse:
 389
 390     .. code-block:: bash
 391
 392         docker tag onap/policy-apex-pdp:latest onap/policy-apex-pdp:opensuse
 393
 394 3. Clone policy/docker repo.
 395
 396 4. Modify docker/csit/docker-compose.yml to use the tagged OpenSuse image.
 397
 398     Replace:
 399
 400     .. code-block:: yaml
 401
 402         apex-pdp:
 403           image: nexus3.onap.org:10001/onap/policy-apex-pdp:${POLICY_APEX_PDP_VERSION}
 404
 405     with:
 406
 407     .. code-block:: yaml
 408
 409         apex-pdp:
 410           image: onap/policy-apex-pdp:opensuse
 411
 412 5. Run the project CSIT. For apex-pdp:
 413
 414     .. code-block:: bash
 415
 416         cd docker/csit
 417         ./run-project-csit.sh apex-pdp
 418
 419     Automated tests will be run, and log files displayed.
 420
 421 Running Policy Components Locally
 422 *********************************
 423
 424 The following page outlines how to run the policy framework components locally use IntelliJ, Eclipse and the Command Line.
 425
 426 .. toctree::
 427    :maxdepth: 1
 428
 429    local-installation.rst
 430
 431
 432 Generating Swagger Documentation
 433 ********************************
 434
 435 1. Accessing Swagger documentation for springboot based policy applications
 436 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 437
 438 Springfox Swagger2 maven dependency aids with auto-generation of Swagger documentation.
 439
 440 Using the Swagger-UI maven dependency Swagger HTML documentation can be accessed at the root url.
 441
 442 - The generated swagger.json can be accessed at: *https://service_IP:service_port/v2/api-docs*
 443 - Swagger UI can be accessed at: *https://service_IP:service_port/swagger-ui/index.html*
 444
 445 Running the DMaaP Simulator during Development
 446 **********************************************
 447 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.
 448
 449 Running on the Command Line
 450 +++++++++++++++++++++++++++
 451 1. Check out the policy models repository
 452 2. Go to the *models-sim/policy-models-simulators* subdirectory in the policy-models repo
 453 3. Run the following Maven command:
 454
 455    .. code-block:: bash
 456
 457       mvn exec:java  -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/simParameters.json"
 458
 459 Running in Eclipse
 460 ++++++++++++++++++
 461 1. Check out the policy models repository
 462 2. Go to the *models-sim/policy-models-simulators* module in the policy-models repo
 463 3. Specify a run configuration using the class *org.onap.policy.models.simulators.Main* as the main class
 464 4. Specify an argument of *src/test/resources/simParameters.json* to the run configuration
 465 5. Run the configuration
 466
 467 Specifying a local configuration file
 468 +++++++++++++++++++++++++++++++++++++
 469
 470 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:
 471
 472 .. code-block:: json
 473
 474    {
 475      "dmaapProvider": {
 476        "name": "DMaaP simulator",
 477        "topicSweepSec": 900
 478      },
 479      "restServers": [
 480        {
 481          "name": "DMaaP simulator",
 482          "providerClass": "org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1",
 483          "host": "localhost",
 484          "port": 3904,
 485          "https": false
 486        }
 487      ]
 488    }
 489
 490 Bringing up Strimzi-Kafka Deploment with Policy Framework
 491 *********************************************************
 492
 493 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.
 494
 495 This is meant for a development purpose only as we are going to use microk8s in this page
 496
 497 .. toctree::
 498    :maxdepth: 1
 499
 500    strimzi-policy.rst