docs/development/devtools/smoke/clamp-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 .. _policy-clamp-runtime-smoke-label:
   6
   7 CLAMP Automation Composition Smoke Tests
   8 ########################################
   9
  10 .. contents::
  11     :depth: 3
  12
  13
  14 This article explains how to build the CLAMP automation composition for development purposes and how to run smoke tests for automation composition. 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`.
  15
  16
  17 This article assumes that:
  18
  19 * You are using a *\*nix* operating system such as linux or macOS.
  20 * You are using a directory called *git* off your home directory *(~/git)* for your git repositories
  21 * Your local maven repository is in the location *~/.m2/repository*
  22 * You have copied the settings.xml from oparent to *~/.m2/* directory
  23 * 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)
  24
  25 The procedure documented in this article has been verified using Ubuntu 20.04 LTS VM.
  26
  27 Cloning CLAMP automation composition and all dependency
  28 *******************************************************
  29
  30 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.
  31
  32 ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module, and the A&AI Schema module.
  33
  34
  35 .. code-block:: bash
  36    :caption: Typical ONAP Policy Framework Clone Script
  37    :linenos:
  38
  39     #!/usr/bin/env bash
  40
  41     ## script name for output
  42     MOD_SCRIPT_NAME='basename $0'
  43
  44     ## the ONAP clone directory, defaults to "onap"
  45     clone_dir="onap"
  46
  47     ## the ONAP repos to clone
  48     onap_repos="\
  49     policy/parent \
  50     policy/common \
  51     policy/models \
  52     policy/clamp "
  53
  54     ##
  55     ## Help screen and exit condition (i.e. too few arguments)
  56     ##
  57     Help()
  58     {
  59         echo ""
  60         echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
  61         echo ""
  62         echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
  63         echo ""
  64         echo "       Options"
  65         echo "         -d          - the ONAP clone directory, defaults to '.'"
  66         echo "         -h          - this help screen"
  67         echo ""
  68         exit 255;
  69     }
  70
  71     ##
  72     ## read command line
  73     ##
  74     while [ $# -gt 0 ]
  75     do
  76         case $1 in
  77             #-d ONAP clone directory
  78             -d)
  79                 shift
  80                 if [ -z "$1" ]; then
  81                     echo "$MOD_SCRIPT_NAME: no clone directory"
  82                     exit 1
  83                 fi
  84                 clone_dir=$1
  85                 shift
  86             ;;
  87
  88             #-h prints help and exists
  89             -h)
  90                 Help;exit 0;;
  91
  92             *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
  93         esac
  94     done
  95
  96     if [ -f "$clone_dir" ]; then
  97         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
  98         exit 2
  99     fi
 100     if [ -d "$clone_dir" ]; then
 101         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
 102         exit 2
 103     fi
 104
 105     mkdir $clone_dir
 106     if [ $? != 0 ]
 107     then
 108         echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
 109         exit 3
 110     fi
 111
 112     for repo in $onap_repos
 113     do
 114         repoDir=`dirname "$repo"`
 115         repoName=`basename "$repo"`
 116
 117         if [ ! -z $dirName ]
 118         then
 119             mkdir "$clone_dir/$repoDir"
 120             if [ $? != 0 ]
 121             then
 122                 echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
 123                 exit 4
 124             fi
 125         fi
 126
 127         git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
 128     done
 129
 130     echo ONAP has been cloned into '"'$clone_dir'"'
 131
 132
 133 Execution of the script above results in the following directory hierarchy in your *~/git* directory:
 134
 135     *  ~/git/onap
 136     *  ~/git/onap/policy
 137     *  ~/git/onap/policy/parent
 138     *  ~/git/onap/policy/common
 139     *  ~/git/onap/policy/models
 140     *  ~/git/onap/policy/clamp
 141
 142
 143 Building CLAMP automation composition and all dependency
 144 ********************************************************
 145
 146 **Step 1:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
 147
 148     .. code-block:: bash
 149
 150         rm -fr ~/.m2/repository/org/onap
 151
 152
 153 **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*.
 154
 155 .. code-block:: xml
 156   :caption: Typical pom.xml to build the ONAP Policy Framework
 157   :linenos:
 158
 159     <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">
 160         <modelVersion>4.0.0</modelVersion>
 161         <groupId>org.onap</groupId>
 162         <artifactId>onap-policy</artifactId>
 163         <version>1.0.0-SNAPSHOT</version>
 164         <packaging>pom</packaging>
 165         <name>${project.artifactId}</name>
 166         <inceptionYear>2023</inceptionYear>
 167         <organization>
 168             <name>ONAP</name>
 169         </organization>
 170
 171         <modules>
 172             <module>parent</module>
 173             <module>common</module>
 174             <module>models</module>
 175             <module>clamp</module>
 176         </modules>
 177     </project>
 178
 179
 180 **Step 3:** You can now build the Policy framework.
 181
 182 Build java artifacts only:
 183
 184     .. code-block:: bash
 185
 186        cd ~/git/onap/policy
 187        mvn clean install
 188
 189 Build with docker images:
 190
 191     .. code-block:: bash
 192
 193        cd ~/git/onap/policy/clamp/packages/
 194        mvn clean install -P docker
 195
 196        cd ~/git/onap/policy/models/models-sim/packages
 197        mvn clean install -P docker
 198
 199 Running MariaDb and DMaaP Simulator
 200 ***********************************
 201
 202 Running a MariaDb Instance
 203 ++++++++++++++++++++++++++
 204
 205 Assuming you have successfully built the codebase using the instructions above. There are two requirements for the Clamp automation composition component to run, one of them is a
 206 running MariaDb database instance. The easiest way to do this is to run the docker image locally.
 207
 208 A sql such as the one below can be used to build the SQL initialization. Create the *mariadb.sql* file in the directory *~/git*.
 209
 210     .. code-block:: SQL
 211
 212        create database clampacm;
 213        CREATE USER 'policy'@'%' IDENTIFIED BY 'P01icY';
 214        GRANT ALL PRIVILEGES ON clampacm.* TO 'policy'@'%';
 215
 216
 217 Execution of the command above results in the creation and start of the *mariadb-smoke-test* container.
 218
 219     .. code-block:: bash
 220
 221        cd ~/git
 222        docker run --name mariadb-smoke-test  \
 223         -p 3306:3306 \
 224         -e MYSQL_ROOT_PASSWORD=my-secret-pw  \
 225         --mount type=bind,source=$HOME/git/mariadb.sql,target=/docker-entrypoint-initdb.d/data.sql \
 226         -d mariadb:10.10.2 \
 227         --lower-case-table-names=1
 228
 229
 230 Running the DMaaP Simulator during Development
 231 ++++++++++++++++++++++++++++++++++++++++++++++
 232 The second requirement for the Clamp automation composition component to run is to run the DMaaP simulator. You can run it from the command line using Maven.
 233
 234
 235 Create a new configuration file *~/git/onap/policy/models/models-sim/policy-models-simulators/src/test/resources/newParameters.json* using the below code:
 236
 237 .. code-block:: json
 238
 239    {
 240      "dmaapProvider": {
 241        "name": "DMaaP simulator",
 242        "topicSweepSec": 900
 243      },
 244      "restServers": [
 245        {
 246          "name": "DMaaP simulator",
 247          "providerClass": "org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1",
 248          "host": "localhost",
 249          "port": 3904,
 250          "https": false
 251        }
 252      ]
 253    }
 254
 255 Run the following commands:
 256
 257    .. code-block:: bash
 258
 259       cd ~/git/onap/policy/models/models-sim/policy-models-simulators
 260       mvn exec:java  -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/newParameters.json"
 261
 262
 263 Developing and Debugging CLAMP automation composition
 264 *****************************************************
 265
 266 Running on the Command Line using Maven
 267 +++++++++++++++++++++++++++++++++++++++
 268
 269 Once the mariadb and DMaap simulator are up and running, run the following commands:
 270
 271    .. code-block:: bash
 272
 273       cd ~/git/onap/policy/clamp/runtime-acm
 274       mvn spring-boot:run
 275
 276
 277 Running on the Command Line
 278 +++++++++++++++++++++++++++
 279
 280    .. code-block:: bash
 281
 282       cd ~/git/onap/policy/clamp/runtime-acm
 283       java -jar target/policy-clamp-runtime-acm-6.4.2-SNAPSHOT.jar
 284
 285
 286 Running in Eclipse
 287 ++++++++++++++++++
 288
 289 1. Check out the policy models repository
 290 2. Go to the *policy-clamp-runtime-acm* module in the clamp repo
 291 3. Where necessary Add as Source Folder 'target/generated-sources/swagger'
 292 4. Specify a run configuration using the class *org.onap.policy.clamp.acm.runtime.Application* as the main class
 293 5. Run the configuration
 294
 295 Swagger UI of Automation composition is available at *http://localhost:6969/onap/policy/clamp/acm/swagger-ui/index.html*
 296
 297
 298 Running one or more participants
 299 ++++++++++++++++++++++++++++++++
 300
 301 Into :ref:`HTTP Participant <clamp-acm-http-participant>` you can find a test case with http-participant.
 302
 303 Run the following commands:
 304
 305    .. code-block:: bash
 306
 307       cd ~/git/onap/policy/clamp/participant/participant-impl/participant-impl-http
 308       java -jar target/policy-clamp-participant-impl-http-6.4.2-SNAPSHOT.jar
 309
 310
 311 Running the CLAMP automation composition docker image
 312 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 313
 314 Create the '*docker-composition.yaml*' using following code:
 315
 316    .. code-block:: yaml
 317
 318       version: '3.1'
 319
 320       services:
 321         mariadb:
 322           image: mariadb:10.10.2
 323           volumes:
 324             - type: bind
 325               source: ./mariadb.sql
 326               target: /docker-entrypoint-initdb.d/data.sql
 327           environment:
 328             - MYSQL_ROOT_PASSWORD=my-secret-pw
 329             - lower-case-table-names=1
 330           ports:
 331             - "3306:3306"
 332
 333         runtime-acm:
 334           image: onap/policy-clamp-runtime-acm
 335           environment:
 336             - mariadb.host=mariadb
 337             - topicServer=message-router
 338           volumes:
 339             - type: bind
 340               source: ./onap/policy/clamp/runtime-acm/src/main/resources/application.yaml
 341               target: /opt/app/policy/clamp/etc/AcRuntimeParameters.yaml
 342           ports:
 343             - "6969:6969"
 344
 345         message-router:
 346           image: onap/policy-models-simulator
 347           volumes:
 348             - type: bind
 349               source: ./onap/policy/models/models-sim/policy-models-simulators/src/test/resources/newParameters.json
 350               target: /opt/app/policy/simulators/etc/mounted/simParameters.json
 351           ports:
 352             - "3904:3904"
 353
 354 Run the docker composition:
 355
 356    .. code-block:: bash
 357
 358       cd ~/git/
 359       docker-compose up
 360
 361
 362 Swagger UI of automation composition is available at *http://localhost:6969/onap/policy/clamp/acm/swagger-ui/index.html*