docs/development/devtools/distribution-s3p.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 .. _distribution-s3p-label:
   6
   7 Policy Distribution component
   8 #############################
   9
  10 72h Stability and 4h Performance Tests of Distribution
  11 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  12
  13 VM Details
  14 ----------
  15
  16 The stability and performance tests are performed on VM's running in the OpenStack cloud
  17 environment in the ONAP integration lab.
  18
  19 **Policy VM details**
  20
  21 - OS: Ubuntu 18.04 LTS (GNU/Linux 4.15.0-151-generic x86_64)
  22 - CPU: 4 core
  23 - RAM: 15 GB
  24 - HardDisk: 39 GB
  25 - Docker version 20.10.7, build 20.10.7-0ubuntu1~18.04.2
  26 - Java: openjdk 11.0.11 2021-04-20
  27
  28
  29 Common Setup
  30 ------------
  31
  32 Update the ubuntu software installer
  33
  34 .. code-block:: bash
  35
  36     sudo apt update
  37
  38 Install Java
  39
  40 .. code-block:: bash
  41
  42     sudo apt install -y openjdk-11-jdk
  43
  44 Ensure that the Java version that is executing is OpenJDK version 11
  45
  46 .. code-block:: bash
  47
  48     $ java --version
  49     openjdk 11.0.11 2021-04-20
  50     OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.18.04)
  51     OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.18.04, mixed mode)
  52
  53 Install Docker and Docker Compose
  54
  55 .. code-block:: bash
  56
  57     # Add docker repository
  58     curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
  59
  60     echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  61     $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  62
  63     sudo apt update
  64
  65     # Install docker
  66     sudo apt-get install docker-ce docker-ce-cli containerd.io
  67
  68 Change the permissions of the Docker socket file
  69
  70 .. code-block:: bash
  71
  72     sudo chmod 666 /var/run/docker.sock
  73
  74 Check the status of the Docker service and ensure it is running correctly
  75
  76 .. code-block:: bash
  77
  78     systemctl status --no-pager docker
  79     docker.service - Docker Application Container Engine
  80        Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
  81        Active: active (running) since Wed 2020-10-14 13:59:40 UTC; 1 weeks 0 days ago
  82        # ... (truncated for brevity)
  83
  84     docker ps
  85     CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
  86
  87 Install and verify docker-compose
  88
  89 .. code-block:: bash
  90
  91     # Install compose
  92     sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  93     sudo chmod +x /usr/local/bin/docker-compose
  94
  95     # Check if install was successful
  96     docker-compose --version
  97
  98 Clone the policy-distribution repo to access the test scripts
  99
 100 .. code-block:: bash
 101
 102     git clone https://gerrit.onap.org/r/policy/distribution
 103
 104 .. _setup-distribution-s3p-components:
 105
 106 Start services for MariaDB, Policy API, PAP and Distribution
 107 ------------------------------------------------------------
 108
 109 Navigate to the main folder for scripts to setup services:
 110
 111 .. code-block:: bash
 112
 113     cd ~/distribution/testsuites/stability/src/main/resources/setup
 114
 115 Modify the versions.sh script to match all the versions being tested.
 116
 117 .. code-block:: bash
 118
 119     vi ~/distribution/testsuites/stability/src/main/resources/setup/versions.sh
 120
 121 Ensure the correct docker image versions are specified - e.g. for Istanbul-M4
 122
 123 - export POLICY_DIST_VERSION=2.6.1-SNAPSHOT
 124
 125 Run the start.sh script to start the components. After installation, script will execute
 126 ``docker ps`` and show the running containers.
 127
 128 .. code-block:: bash
 129
 130     ./start.sh
 131
 132     Creating network "setup_default" with the default driver
 133     Creating policy-distribution ... done
 134     Creating mariadb             ... done
 135     Creating simulator           ... done
 136     Creating policy-db-migrator  ... done
 137     Creating policy-api          ... done
 138     Creating policy-pap          ... done
 139
 140     CONTAINER ID   IMAGE                                                               COMMAND                  CREATED         STATUS                  PORTS                NAMES
 141     f91be98ad1f4   nexus3.onap.org:10001/onap/policy-pap:2.5.1-SNAPSHOT                "/opt/app/policy/pap…"   1 second ago    Up Less than a second   6969/tcp             policy-pap
 142     d92cdbe971d4   nexus3.onap.org:10001/onap/policy-api:2.5.1-SNAPSHOT                "/opt/app/policy/api…"   1 second ago    Up Less than a second   6969/tcp             policy-api
 143     9a019f5d641e   nexus3.onap.org:10001/onap/policy-db-migrator:2.3.1-SNAPSHOT        "/opt/app/policy/bin…"   2 seconds ago   Up 1 second             6824/tcp             policy-db-migrator
 144     108ba238edeb   nexus3.onap.org:10001/mariadb:10.5.8                                "docker-entrypoint.s…"   3 seconds ago   Up 1 second             3306/tcp             mariadb
 145     bec9b223e79f   nexus3.onap.org:10001/onap/policy-models-simulator:2.5.1-SNAPSHOT   "simulators.sh"          3 seconds ago   Up 1 second             3905/tcp             simulator
 146     74aa5abeeb08   nexus3.onap.org:10001/onap/policy-distribution:2.6.1-SNAPSHOT       "/opt/app/policy/bin…"   3 seconds ago   Up 1 second             6969/tcp, 9090/tcp   policy-distribution
 147
 148
 149 .. note::
 150     The containers on this docker-compose are running with HTTP configuration. For HTTPS, ports
 151     and configurations will need to be changed, as well certificates and keys must be generated
 152     for security.
 153
 154
 155 Install JMeter
 156 --------------
 157
 158 Download and install JMeter
 159
 160 .. code-block:: bash
 161
 162     # Install required packages
 163     sudo apt install -y wget unzip
 164
 165     # Install JMeter
 166     mkdir -p jmeter
 167     cd jmeter
 168     wget https://dlcdn.apache.org//jmeter/binaries/apache-jmeter-5.4.1.zip
 169     unzip -q apache-jmeter-5.4.1.zip
 170     rm apache-jmeter-5.4.1.zip
 171
 172
 173 Install & configure visualVM
 174 --------------------------------------
 175
 176 VisualVM needs to be installed in the virtual machine running Distribution. It will be used to
 177 monitor CPU, Memory and GC for Distribution while the stability tests are running.
 178
 179 .. code-block:: bash
 180
 181     sudo apt install -y visualvm
 182
 183 Run these commands to configure permissions
 184
 185 .. code-block:: bash
 186
 187     # Set globally accessable permissions on policy file
 188     sudo chmod 777 /usr/lib/jvm/java-11-openjdk-amd64/bin/visualvm.policy
 189
 190     # Create Java security policy file for VisualVM
 191     sudo cat > /usr/lib/jvm/java-11-openjdk-amd64/bin/visualvm.policy << EOF
 192     grant codebase "jrt:/jdk.jstatd" {
 193        permission java.security.AllPermission;
 194     };
 195     grant codebase "jrt:/jdk.internal.jvmstat" {
 196        permission java.security.AllPermission;
 197     };
 198     EOF
 199
 200 Run the following command to start jstatd using port 1111
 201
 202 .. code-block:: bash
 203
 204     /usr/lib/jvm/java-11-openjdk-amd64/bin/jstatd -p 1111 -J-Djava.security.policy=/usr/lib/jvm/java-11-openjdk-amd64/bin/visualvm.policy &
 205
 206 Run visualVM to connect to POLICY_DISTRIBUTION_IP:9090
 207
 208 .. code-block:: bash
 209
 210     # Get the Policy Distribution container IP
 211     echo $(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' policy-distribution)
 212
 213     # Start visual vm
 214     visualvm &
 215
 216 This will load up the visualVM GUI
 217
 218 Connect to Distribution JMX Port.
 219
 220     1. On the visualvm toolbar, click on "Add JMX Connection"
 221     2. Enter the Distribution container IP and Port 9090. This is the JMX port exposed by the
 222        distribution container
 223     3. Double click on the newly added nodes under "Remotes" to start monitoring CPU, Memory & GC.
 224
 225 Example Screenshot of visualVM
 226
 227 .. image:: distribution-s3p-results/distribution-visualvm-snapshot.png
 228
 229
 230 Stability Test of Policy Distribution
 231 +++++++++++++++++++++++++++++++++++++
 232
 233 Introduction
 234 ------------
 235
 236 The 72 hour Stability Test for policy distribution has the goal of introducing a steady flow of
 237 transactions initiated from a test client server running JMeter. The policy distribution is
 238 configured with a special FileSystemReception plugin to monitor a local directory for newly added
 239 csar files to be processed by itself. The input CSAR will be added/removed by the test client
 240 (JMeter) and the result will be pulled from the backend (PAP and PolicyAPI) by the test client
 241 (JMeter).
 242
 243 The test will be performed in an environment where Jmeter will continuously add/remove a test csar
 244 into the special directory where policy distribution is monitoring and will then get the processed
 245 results from PAP and PolicyAPI to verify the successful deployment of the policy. The policy will
 246 then be undeployed and the test will loop continuously until 72 hours have elapsed.
 247
 248
 249 Test Plan Sequence
 250 ------------------
 251
 252 The 72h stability test will run the following steps sequentially in a single threaded loop.
 253
 254 - **Delete Old CSAR** - Checks if CSAR already exists in the watched directory, if so it deletes it
 255 - **Add CSAR** - Adds CSAR to the directory that distribution is watching
 256 - **Get Healthcheck** - Ensures Healthcheck is returning 200 OK
 257 - **Get Statistics** - Ensures Statistics is returning 200 OK
 258 - **Assert PDP Group Query** - Checks that PDPGroupQuery contains the deployed policy
 259 - **Assert PoliciesDeployed** - Checks that the policy is deployed
 260 - **Undeploy/Delete Policy** - Undeploys and deletes the Policy for the next loop
 261 - **Assert PDP Group Query for Deleted Policy** - Ensures the policy has been removed and does not exist
 262
 263 The following steps can be used to configure the parameters of the test plan.
 264
 265 - **HTTP Authorization Manager** - used to store user/password authentication details.
 266 - **HTTP Header Manager** - used to store headers which will be used for making HTTP requests.
 267 - **User Defined Variables** -  used to store following user defined parameters.
 268
 269 ==========  ===============================================
 270  **Name**    **Description**
 271 ==========  ===============================================
 272  PAP_HOST     IP Address or host name of PAP component
 273  PAP_PORT     Port number of PAP for making REST API calls
 274  API_HOST     IP Address or host name of API component
 275  API_PORT     Port number of API for making REST API calls
 276  DURATION     Duration of Test
 277 ==========  ===============================================
 278
 279 Screenshot of Distribution stability test plan
 280
 281 .. image:: distribution-s3p-results/distribution-jmeter-testcases.png
 282
 283
 284 Running the Test Plan
 285 ---------------------
 286
 287 Check if the /tmp/policydistribution/distributionmount exists as it was created during the start.sh
 288 script execution. If not, run the following commands to create folder and change folder permissions
 289 to allow the testplan to insert the CSAR into the /tmp/policydistribution/distributionmount folder.
 290
 291 .. note::
 292     Make sure that only csar file is being loaded in the watched folder and log generation is in a
 293     logs folder, as any sort of zip file can be understood by distribution as a policy file. A
 294     logback.xml configuration file is available under setup/distribution folder.
 295
 296 .. code-block:: bash
 297
 298     sudo mkdir -p /tmp/policydistribution/distributionmount
 299     sudo chmod -R a+trwx /tmp
 300
 301
 302 Navigate to the stability test folder.
 303
 304 .. code-block:: bash
 305
 306     cd ~/distribution/testsuites/stability/src/main/resources/testplans/
 307
 308 Execute the run_test.sh
 309
 310 .. code-block:: bash
 311
 312     ./run_test.sh
 313
 314
 315 Test Results
 316 ------------
 317
 318 **Summary**
 319
 320 - Stability test plan was triggered for 72 hours.
 321 - No errors were reported
 322
 323 **Test Statistics**
 324
 325 .. image:: distribution-s3p-results/stability-statistics.png
 326 .. image:: distribution-s3p-results/stability-threshold.png
 327
 328 **VisualVM Screenshots**
 329
 330 .. image:: distribution-s3p-results/stability-monitor.png
 331 .. image:: distribution-s3p-results/stability-threads.png
 332
 333
 334 Performance Test of Policy Distribution
 335 +++++++++++++++++++++++++++++++++++++++
 336
 337 Introduction
 338 ------------
 339
 340 The 4h Performance Test of Policy Distribution has the goal of testing the min/avg/max processing
 341 time and rest call throughput for all the requests when the number of requests are large enough to
 342 saturate the resource and find the bottleneck.
 343
 344 It also tests that distribution can handle multiple policy CSARs and that these are deployed within
 345 30 seconds consistently.
 346
 347
 348 Setup Details
 349 -------------
 350
 351 The performance test is based on the same setup as the distribution stability tests.
 352
 353
 354 Test Plan Sequence
 355 ------------------
 356
 357 Performance test plan is different from the stability test plan.
 358
 359 - Instead of handling one policy csar at a time, multiple csar's are deployed within the watched
 360   folder at the exact same time.
 361 - We expect all policies from these csar's to be deployed within 30 seconds.
 362 - There are also multithreaded tests running towards the healthcheck and statistics endpoints of
 363   the distribution service.
 364
 365
 366 Running the Test Plan
 367 ---------------------
 368
 369 Check if /tmp folder permissions to allow the Testplan to insert the CSAR into the
 370 /tmp/policydistribution/distributionmount folder.
 371 Clean up from previous run. If necessary, put containers down with script `down.sh` from setup
 372 folder mentioned on :ref:`Setup components <setup-distribution-s3p-components>`
 373
 374 .. code-block:: bash
 375
 376     sudo mkdir -p /tmp/policydistribution/distributionmount
 377     sudo chmod -R a+trwx /tmp
 378
 379 Navigate to the testplan folder and execute the test script:
 380
 381 .. code-block:: bash
 382
 383     cd ~/distribution/testsuites/performance/src/main/resources/testplans/
 384     ./run_test.sh
 385
 386
 387 Test Results
 388 ------------
 389
 390 **Summary**
 391
 392 - Performance test plan was triggered for 4 hours.
 393 - No errors were reported
 394
 395 **Test Statistics**
 396
 397 .. image:: distribution-s3p-results/performance-statistics.png
 398 .. image:: distribution-s3p-results/performance-threshold.png
 399
 400 **VisualVM Screenshots**
 401
 402 .. image:: distribution-s3p-results/performance-monitor.png
 403 .. image:: distribution-s3p-results/performance-threads.png