docs/development/devtools/smoke/policy-participant-smoke.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 CLAMP Policy Participant Smoke Tests
   6 ------------------------------------
   7
   8 1. Introduction
   9 ***************
  10
  11 The Smoke testing of the policy participant is executed in a local CLAMP/Policy environment. The CLAMP-ACM interfaces interact with the Policy Framework to perform actions based on the state of the policy participant. The goal of the Smoke tests is the ensure that CLAMP Policy Participant and Policy Framework work together as expected.
  12 All applications will be running by console, so they need to run with different ports. Configuration files should be changed accordingly.
  13
  14 +------------------------------+-------+
  15 | Application                  |  port |
  16 +==============================+=======+
  17 | MariDB                       |  3306 |
  18 +------------------------------+-------+
  19 | Zookeeper                    |  2181 |
  20 +------------------------------+-------+
  21 | Kafka                        | 29092 |
  22 +------------------------------+-------+
  23 | policy-api                   |  6968 |
  24 +------------------------------+-------+
  25 | policy-pap                   |  6970 |
  26 +------------------------------+-------+
  27 | policy-clamp-runtime-acm     |  6969 |
  28 +------------------------------+-------+
  29 | onap/policy-clamp-ac-pf-ppnt |  8085 |
  30 +------------------------------+-------+
  31
  32
  33 2. Setup Guide
  34 **************
  35
  36 This section will show the developer how to set up their environment to start testing in GUI with some instruction on how to carry out the tests. There are several prerequisites. Note that this guide is written by a Linux user - although the majority of the steps show will be exactly the same in Windows or other systems.
  37
  38 2.1 Prerequisites
  39 =================
  40
  41 - Java 17
  42 - Maven 3.9
  43 - Git
  44 - Refer to this guide for basic environment setup `Setting up dev environment <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_
  45
  46 2.2 Cloning CLAMP automation composition and all dependency
  47 ===========================================================
  48
  49 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 CLAMP automation composition and all dependency.
  50
  51 .. code-block:: bash
  52    :caption: Typical ONAP Policy Framework Clone Script
  53    :linenos:
  54
  55     #!/usr/bin/env bash
  56
  57     ## script name for output
  58     MOD_SCRIPT_NAME='basename $0'
  59
  60     ## the ONAP clone directory, defaults to "onap"
  61     clone_dir="onap"
  62
  63     ## the ONAP repos to clone
  64     onap_repos="\
  65     policy/api \
  66     policy/clamp \
  67     policy/pap "
  68
  69     ##
  70     ## Help screen and exit condition (i.e. too few arguments)
  71     ##
  72     Help()
  73     {
  74         echo ""
  75         echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
  76         echo ""
  77         echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
  78         echo ""
  79         echo "       Options"
  80         echo "         -d          - the ONAP clone directory, defaults to '.'"
  81         echo "         -h          - this help screen"
  82         echo ""
  83         exit 255;
  84     }
  85
  86     ##
  87     ## read command line
  88     ##
  89     while [ $# -gt 0 ]
  90     do
  91         case $1 in
  92             #-d ONAP clone directory
  93             -d)
  94                 shift
  95                 if [ -z "$1" ]; then
  96                     echo "$MOD_SCRIPT_NAME: no clone directory"
  97                     exit 1
  98                 fi
  99                 clone_dir=$1
 100                 shift
 101             ;;
 102
 103             #-h prints help and exists
 104             -h)
 105                 Help;exit 0;;
 106
 107             *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
 108         esac
 109     done
 110
 111     if [ -f "$clone_dir" ]; then
 112         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
 113         exit 2
 114     fi
 115     if [ -d "$clone_dir" ]; then
 116         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
 117         exit 2
 118     fi
 119
 120     mkdir $clone_dir
 121     if [ $? != 0 ]
 122     then
 123         echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
 124         exit 3
 125     fi
 126
 127     for repo in $onap_repos
 128     do
 129         repoDir=`dirname "$repo"`
 130         repoName=`basename "$repo"`
 131
 132         if [ ! -z $dirName ]
 133         then
 134             mkdir "$clone_dir/$repoDir"
 135             if [ $? != 0 ]
 136             then
 137                 echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
 138                 exit 4
 139             fi
 140         fi
 141
 142         git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
 143     done
 144
 145     echo ONAP has been cloned into '"'$clone_dir'"'
 146
 147
 148 Execution of the script above results in the following directory hierarchy in your *~/git* directory:
 149
 150     *  ~/git/onap
 151     *  ~/git/onap/policy
 152     *  ~/git/onap/policy/api
 153     *  ~/git/onap/policy/clamp
 154     *  ~/git/onap/policy/pap
 155
 156
 157 2.3 Building CLAMP automation composition and all dependency
 158 ============================================================
 159
 160 **Step 1:** Setting topicParameterGroup for kafka localhost in clamp and policy-participant.
 161 It needs to set 'kafka' as topicCommInfrastructure and 'localhost:29092' as server.
 162 In the clamp repo, you should find the file 'runtime-acm/src/main/resources/application.yaml'. This file (in the 'runtime' parameters section) may need to be altered as below:
 163
 164 .. literalinclude:: files/runtime-application.yaml
 165    :language: yaml
 166
 167 Setting topicParameterGroup for kafka localhost and api/pap http client (in the 'participant' parameters section) may need to be apply into the file 'participant/participant-impl/participant-impl-policy/src/main/resources/config/application.yaml'.
 168
 169 .. literalinclude:: files/participant-policy-application.yaml
 170    :language: yaml
 171
 172
 173 **Step 2:** Setting datasource.url, hibernate.ddl-auto and server.port in policy-api.
 174 In the api repo, you should find the file 'main/src/main/resources/application.yaml'. This file may need to be altered as below:
 175
 176 .. literalinclude:: files/api-application.yaml
 177    :language: yaml
 178
 179
 180 **Step 3:** Setting datasource.url, server.port, and api http client in policy-pap.
 181 In the pap repo, you should find the file 'main/src/main/resources/application.yaml'. This file may need to be altered as below:
 182
 183 .. literalinclude:: files/pap-application.yaml
 184    :language: yaml
 185
 186
 187 **Step 4:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
 188
 189     .. code-block:: bash
 190
 191         rm -fr ~/.m2/repository/org/onap
 192
 193
 194 **Step 5:**  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*.
 195
 196 .. code-block:: xml
 197   :caption: Typical pom.xml to build the ONAP Policy Framework
 198   :linenos:
 199
 200     <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">
 201         <modelVersion>4.0.0</modelVersion>
 202         <groupId>org.onap</groupId>
 203         <artifactId>onap-policy</artifactId>
 204         <version>1.0.0-SNAPSHOT</version>
 205         <packaging>pom</packaging>
 206         <name>${project.artifactId}</name>
 207         <inceptionYear>2024</inceptionYear>
 208         <organization>
 209             <name>ONAP</name>
 210         </organization>
 211
 212         <modules>
 213             <module>api</module>
 214             <module>clamp</module>
 215             <module>pap</module>
 216         </modules>
 217     </project>
 218
 219
 220 **Step 6:** You can now build the Policy framework.
 221
 222 Build java artifacts only:
 223
 224     .. code-block:: bash
 225
 226        cd ~/git/onap/policy
 227        mvn clean install -DskipTests
 228
 229 Build with docker images:
 230
 231     .. code-block:: bash
 232
 233        cd ~/git/onap/policy/clamp/packages/
 234        mvn clean install -P docker
 235
 236        cd ~/git/onap/policy/api/packages/
 237        mvn clean install -P docker
 238
 239        cd ~/git/onap/policy/pap/packages/
 240        mvn clean install -P docker
 241
 242 2.4 Setting up the components
 243 =============================
 244
 245 2.4.1 MariaDB and Kafka Setup
 246 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 247
 248 We will be using Docker to run our mariadb instance`and Zookeeper/Kafka. It will have a total of two databases running in mariadb.
 249
 250 - clampacm: the policy-clamp-runtime-acm db
 251 - policyadmin: the policy-api db
 252
 253 **Step 1:** Create the *mariadb.sql* file in a directory *~/git*.
 254
 255     .. code-block:: SQL
 256
 257        create database clampacm;
 258        CREATE USER 'policy'@'%' IDENTIFIED BY 'P01icY';
 259        GRANT ALL PRIVILEGES ON clampacm.* TO 'policy'@'%';
 260        CREATE DATABASE `policyadmin`;
 261        CREATE USER 'policy_user'@'%' IDENTIFIED BY 'policy_user';
 262        GRANT ALL PRIVILEGES ON policyadmin.* to 'policy_user'@'%';
 263        CREATE DATABASE `migration`;
 264        GRANT ALL PRIVILEGES ON migration.* to 'policy_user'@'%';
 265        FLUSH PRIVILEGES;
 266
 267
 268 **Step 2:** Create the *init.sh* file in a directory *~/git* with execution permission.
 269
 270     .. code-block:: sh
 271
 272        #!/bin/sh
 273
 274        export POLICY_HOME=/opt/app/policy
 275        export SQL_USER=${MYSQL_USER}
 276        export SQL_PASSWORD=${MYSQL_PASSWORD}
 277        export SCRIPT_DIRECTORY=sql
 278
 279        /opt/app/policy/bin/prepare_upgrade.sh ${SQL_DB}
 280        /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 281        /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o upgrade
 282        rc=$?
 283        /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 284        nc -l -p 6824
 285        exit $rc
 286
 287
 288 **Step 3:** Create the *wait_for_port.sh* file in a directory *~/git* with execution permission.
 289
 290     .. code-block:: sh
 291
 292        #!/bin/sh
 293
 294        usage() {
 295          echo args: [-t timeout] [-c command] hostname1 port1 hostname2 port2 ... >&2
 296          exit 1
 297        }
 298        tmout=300
 299        cmd=
 300        while getopts c:t: opt
 301        do
 302            case "$opt" in
 303                c)
 304                    cmd="$OPTARG"
 305                    ;;
 306                t)
 307                    tmout="$OPTARG"
 308                    ;;
 309                *)
 310                    usage
 311                    ;;
 312            esac
 313        done
 314        nargs=$((OPTIND-1))
 315        shift "$nargs"
 316        even_args=$(($#%2))
 317        if [ $# -lt 2 ] || [ "$even_args" -ne 0 ]
 318        then
 319            usage
 320        fi
 321        while [ $# -ge 2 ]
 322        do
 323            export host="$1"
 324            export port="$2"
 325            shift
 326            shift
 327            echo "Waiting for $host port $port..."
 328
 329            while [ "$tmout" -gt 0 ]
 330            do
 331                if command -v docker > /dev/null 2>&1
 332                then
 333                    docker ps --format "table {{ .Names }}\t{{ .Status }}"
 334                fi
 335                nc -vz "$host" "$port"
 336                rc=$?
 337                if [ $rc -eq 0 ]
 338                then
 339                    break
 340                else
 341                    tmout=$((tmout-1))
 342                    sleep 1
 343                fi
 344            done
 345            if [ $rc -ne 0 ]
 346            then
 347                echo "$host port $port cannot be reached"
 348                exit $rc
 349            fi
 350        done
 351        $cmd
 352        exit 0
 353
 354
 355 **Step 4:** Create the '*docker-compose.yaml*' using following code:
 356
 357 .. literalinclude:: files/docker-compose-policy.yaml
 358    :language: yaml
 359
 360
 361 **Step 5:** Run the docker composition:
 362
 363    .. code-block:: bash
 364
 365       cd ~/git/
 366       docker compose up
 367
 368
 369 2.4.2 Policy API
 370 ^^^^^^^^^^^^^^^^
 371
 372 In the policy-api repo, navigate to the "/main" directory. You can then run the following command to start the policy api:
 373
 374 .. code-block:: bash
 375
 376     mvn spring-boot:run
 377
 378
 379 2.4.3 Policy PAP
 380 ^^^^^^^^^^^^^^^^
 381
 382 In the policy-pap repo, navigate to the "/main" directory. You can then run the following command to start the policy pap:
 383
 384 .. code-block:: bash
 385
 386     mvn spring-boot:run
 387
 388 2.4.4 ACM Runtime
 389 ^^^^^^^^^^^^^^^^^
 390
 391 To start the clampacm runtime we need to go the "runtime-acm" directory in the clamp repo. You can then run the following command to start the clampacm runtime:
 392
 393 .. code-block:: bash
 394
 395     mvn spring-boot:run
 396
 397 2.4.5 ACM Policy Participant
 398 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 399
 400 To start the policy participant we need to go to the "participant/participant-impl/participant-impl-policy" directory in the clamp repo. You can then run the following command to start the policy-participant:
 401
 402 .. code-block:: bash
 403
 404     mvn spring-boot:run
 405
 406 3. Testing Procedure
 407 ====================
 408
 409 3.1 Testing Outline
 410 ^^^^^^^^^^^^^^^^^^^
 411
 412 To perform the Smoke testing of the policy-participant we will be verifying the behaviours of the participant when the ACM changes state. The scenarios are:
 413
 414 - UNDEPLOYED to DEPLOYED: participant creates policies and policyTypes specified in the ToscaServiceTemplate using policy-api and deploys the policies using pap.
 415 - LOCK to UNLOCK: participant changes lock state to UNLOCK. No operation performed.
 416 - UNLOCK to LOCK: participant changes lock state to LOCK. No operation performed.
 417 - DEPLOYED to UNDEPLOYED: participant undeploys deployed policies and deletes policies and policyTypes which have been created.
 418
 419 3.2 Testing Steps
 420 ^^^^^^^^^^^^^^^^^
 421
 422 Creation of AC Definition:
 423 **************************
 424 An AC Definition is created by commissioning a Tosca template.
 425 Using postman, commission a TOSCA template using the following template:
 426
 427 :download:`Tosca Service Template <tosca/tosca_service_template_pptnt_smoke.yaml>`
 428
 429 To verify this, we check that the AC Definition has been created and is in state COMMISSIONED.
 430
 431     .. image:: images/pol-part-clampacm-get-composition.png
 432
 433 Priming AC Definition:
 434 **********************
 435 The AC Definition state is changed from COMMISSIONED to PRIMED using postman:
 436
 437 .. code-block:: json
 438
 439     {
 440         "primeOrder": "PRIME"
 441     }
 442
 443
 444 To verify this, we check that the AC Definition has been primed.
 445
 446     .. image:: images/pol-part-clampacm-get-primed-composition.png
 447
 448
 449 Creation of AC Instance:
 450 ************************
 451 Using postman, instance the AC definition using the following template:
 452
 453 :download:`Instantiate ACM <json/instantiation_pptnt_smoke.json>`
 454
 455 To verify this, we check that the AC Instance has been created and is in state UNDEPLOYED.
 456
 457     .. image:: images/pol-part-clampacm-creation-ver.png
 458
 459 Creation and deploy of policies and policyTypes:
 460 ************************************************
 461 The AC Instance deploy state is changed from UNDEPLOYED to DEPLOYED using postman:
 462
 463 .. code-block:: json
 464
 465     {
 466         "deployOrder": "DEPLOY"
 467     }
 468
 469 This state change will trigger the creation of policies and policyTypes using the policy-api and the deployment of the policies specified in the ToscaServiceTemplate.
 470 To verify this we will check, using policy-api endpoints, that the onap.policies.native.apex.ac.element policy, which is specified in the service template, has been created.
 471
 472     .. image:: images/pol-part-clampacm-ac-policy-ver.png
 473
 474 And we will check that the apex onap.policies.native.apex.ac.element policy has been deployed to the defaultGroup. We check this using pap:
 475
 476     .. image:: images/pol-part-clampacm-ac-deploy-ver.png
 477
 478 Undeployment and deletion of policies and policyTypes:
 479 ******************************************************
 480 The ACM STATE is changed from DEPLOYED to UNDEPLOYED using postman:
 481
 482 .. code-block:: json
 483
 484     {
 485         "deployOrder": "UNDEPLOY"
 486     }
 487
 488 This state change will trigger the undeployment of the onap.policies.native.apex.ac.element policy which was deployed previously and the deletion of the previously created policies and policyTypes.
 489 To verify this we do a PdpGroup Query as before and check that the onap.policies.native.apex.ac.element policy has been undeployed and removed from the defaultGroup:
 490
 491     .. image:: images/pol-part-clampacm-ac-undep-ver.png
 492
 493
 494 As before, we can check that the Test Policy policyType is not found this time and likewise for the onap.policies.native.apex.ac.element policy:
 495
 496     .. image:: images/pol-part-clampacm-test-policy-nf.png