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    policy-gui-acm-smoke.rst
 306    db-migrator-smoke.rst
 307    smoke/acm-participants-smoke.rst
 308    smoke/clamp-smoke.rst
 309    clamp-cl-participant-protocol-smoke.rst
 310    policy-participant-smoke.rst
 311    api-smoke.rst
 312    pap-smoke.rst
 313    apex-smoke.rst
 314    drools-smoke.rst
 315    xacml-smoke.rst
 316    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    clamp-policy.rst
 348
 349    clamp-dcae.rst
 350
 351    policy-cds.rst
 352
 353    clamp-sdc.rst
 354
 355 ..
 356    api-pairwise.rst
 357
 358 ..
 359    pap-pairwise.rst
 360
 361 ..
 362    apex-pairwise.rst
 363
 364 ..
 365    drools-pairwise.rst
 366
 367 ..
 368    xacml-pairwise.rst
 369
 370 ..
 371    distribution-pairwise.rst
 372
 373
 374 Testing OpenSuse docker images
 375 ******************************
 376
 377 Policy Framework offers docker images in two flavors: Alpine and OpenSuse.
 378 Alpine images are used in OOM for ONAP deployments.
 379 The OpenSuse images are built manually if needed, by running Maven with the -Pdockersuse profile.
 380 To test these images, CSITs will be run.
 381
 382 1. Build the OpenSuse image you want by running Maven with -Pdockersuse:
 383
 384     .. code-block:: bash
 385
 386         cd policy/apex-pdp
 387         mvn clean install -Pdockersuse
 388
 389     The image onap/policy-apex-pdp:latest will be produced.
 390
 391 2. To avoid ambiguity, tag the image as opensuse:
 392
 393     .. code-block:: bash
 394
 395         docker tag onap/policy-apex-pdp:latest onap/policy-apex-pdp:opensuse
 396
 397 3. Clone policy/docker repo.
 398
 399 4. Modify docker/csit/docker-compose.yml to use the tagged OpenSuse image.
 400
 401     Replace:
 402
 403     .. code-block:: yaml
 404
 405         apex-pdp:
 406           image: nexus3.onap.org:10001/onap/policy-apex-pdp:${POLICY_APEX_PDP_VERSION}
 407
 408     with:
 409
 410     .. code-block:: yaml
 411
 412         apex-pdp:
 413           image: onap/policy-apex-pdp:opensuse
 414
 415 5. Run the project CSIT. For apex-pdp:
 416
 417     .. code-block:: bash
 418
 419         cd docker/csit
 420         ./run-project-csit.sh apex-pdp
 421
 422     Automated tests will be run, and log files displayed.
 423
 424 Running Policy Components Locally
 425 *********************************
 426
 427 The following page outlines how to run the policy framework components locally use IntelliJ, Eclipse and the Command Line.
 428
 429 .. toctree::
 430    :maxdepth: 1
 431
 432    local-installation.rst
 433
 434
 435 Generating Swagger Documentation
 436 ********************************
 437
 438 1. Accessing Swagger documentation for springboot based policy applications
 439 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 440
 441 Springfox Swagger2 maven dependency aids with auto-generation of Swagger documentation.
 442
 443 Using the Swagger-UI maven dependency Swagger HTML documentation can be accessed at the root url.
 444
 445 - The generated swagger.json can be accessed at: *https://service_IP:service_port/v2/api-docs*
 446 - Swagger UI can be accessed at: *https://service_IP:service_port/swagger-ui/index.html*
 447
 448 Running the DMaaP Simulator during Development
 449 **********************************************
 450 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.
 451
 452 Running on the Command Line
 453 +++++++++++++++++++++++++++
 454 1. Check out the policy models repository
 455 2. Go to the *models-sim/policy-models-simulators* subdirectory in the policy-models repo
 456 3. Run the following Maven command:
 457
 458    .. code-block:: bash
 459
 460       mvn exec:java  -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/simParameters.json"
 461
 462 Running in Eclipse
 463 ++++++++++++++++++
 464 1. Check out the policy models repository
 465 2. Go to the *models-sim/policy-models-simulators* module in the policy-models repo
 466 3. Specify a run configuration using the class *org.onap.policy.models.simulators.Main* as the main class
 467 4. Specify an argument of *src/test/resources/simParameters.json* to the run configuration
 468 5. Run the configuration
 469
 470 Specifying a local configuration file
 471 +++++++++++++++++++++++++++++++++++++
 472
 473 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:
 474
 475 .. code-block:: json
 476
 477    {
 478      "dmaapProvider": {
 479        "name": "DMaaP simulator",
 480        "topicSweepSec": 900
 481      },
 482      "restServers": [
 483        {
 484          "name": "DMaaP simulator",
 485          "providerClass": "org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1",
 486          "host": "localhost",
 487          "port": 3904,
 488          "https": false
 489        }
 490      ]
 491    }
 492
 493 Bringing up Strimzi-Kafka Deploment with Policy Framework
 494 *********************************************************
 495
 496 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.
 497
 498 This is meant for a development purpose only as we are going to use microk8s in this page
 499
 500 .. toctree::
 501    :maxdepth: 1
 502
 503    strimzi-policy.rst