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