docs/development/devtools/cl-participants-smoke.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-controlloop-participants-smoke-tests:
   4
   5 CLAMP participants (kubernetes, http) Smoke Tests
   6 -------------------------------------------------
   7 1. Introduction
   8 ***************
   9 The CLAMP participants (kubernetes and http) are used to interact with the helm client in a kubernetes environment for the
  10 deployment of microservices via helm chart as well as to configure the microservices over REST endpoints. Both of these participants are
  11 often used together in the Control loop workflow.
  12
  13 This document will serve as a guide to do smoke tests on the different components that are involved when working with the participants and outline how they operate. It will also show a developer how to set up their environment for carrying out smoke tests on these participants.
  14
  15 2. Setup Guide
  16 **************
  17 This article assumes that:
  18
  19 * You are using the operating systems such as linux/macOS/windows.
  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 2.1 Prerequisites
  28 =================
  29 - Java 11
  30 - Docker
  31 - Maven 3
  32 - Git
  33 - helm3
  34 - k8s cluster
  35 - Refer to this guide for basic environment setup `Setting up dev environment <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_
  36
  37 2.2 Assumptions
  38 ===============
  39 - You are accessing the policy repositories through gerrit.
  40
  41 The following repositories are required for development in this project. These repositories should be present on your machine and you should run "mvn clean install" on all of them so that the packages are present in your .m2 repository.
  42
  43 - policy/parent
  44 - policy/common
  45 - policy/models
  46 - policy/clamp
  47 - policy/docker
  48
  49 In this setup guide, we will be setting up all the components technically required for a working dev environment.
  50
  51 2.3 Setting up the components
  52 =============================
  53
  54 2.3.1 MariaDB Setup
  55 ^^^^^^^^^^^^^^^^^^^
  56 We will be using Docker to run our mariadb instance. It will have the runtime-controlloop database running in it.
  57
  58 - controlloop: the runtime-controlloop db
  59
  60 The easiest way to do this is to perform a small alteration on an SQL script provided by the clamp backend in the file "runtime/extra/sql/bulkload/create-db.sql"
  61
  62 .. code-block:: mysql
  63
  64     CREATE DATABASE `controlloop`;
  65     USE `controlloop`;
  66     DROP USER 'policy';
  67     CREATE USER 'policy';
  68     GRANT ALL on controlloop.* to 'policy' identified by 'P01icY' with GRANT OPTION;
  69
  70 Once this has been done, we can run the bash script provided here: "runtime/extra/bin-for-dev/start-db.sh"
  71
  72 .. code-block:: bash
  73
  74     ./start-db.sh
  75
  76 This will setup all the Control Loop runtime database. The database will be exposed locally on port 3306 and will be backed by an anonymous docker volume.
  77
  78 2.3.2 DMAAP Simulator
  79 ^^^^^^^^^^^^^^^^^^^^^
  80 For convenience, a dmaap simulator has been provided in the policy/models repository. To start the simulator, you can do the following:
  81
  82 1. Navigate to /models-sim/policy-models-simulators in the policy/models repository.
  83 2. Add a configuration file to src/test/resources with the following contents:
  84
  85 .. code-block:: json
  86
  87     {
  88        "dmaapProvider":{
  89           "name":"DMaaP simulator",
  90           "topicSweepSec":900
  91        },
  92        "restServers":[
  93           {
  94              "name":"DMaaP simulator",
  95              "providerClass":"org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1",
  96              "host":"localhost",
  97              "port":3904,
  98              "https":false
  99           }
 100        ]
 101     }
 102
 103 3. You can then start dmaap with:
 104
 105 .. code-block:: bash
 106
 107     mvn exec:java  -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/YOUR_CONF_FILE.json"
 108
 109 At this stage the dmaap simulator should be running on your local machine on port 3904.
 110
 111
 112 2.3.3 Controlloop Runtime
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^
 114 To start the controlloop runtime service, we need to execute the following maven command from the "runtime-controlloop" directory in the clamp repo. Control Loop runtime uses the config file "src/main/resources/application.yaml" by default.
 115
 116 .. code-block:: bash
 117
 118     mvn spring-boot:run
 119
 120 2.3.4 Helm chart repository
 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 122 Kubernetes participant consumes helm charts from the local chart database as well as from a helm repository. For the smoke testing, we are going to add `nginx-stable` helm repository to the helm client.
 123 The following command can be used to add nginx repository to the helm client.
 124
 125 .. code-block:: bash
 126
 127     helm repo add nginx-stable https://helm.nginx.com/stable
 128
 129 2.3.5 Kubernetes and http participants
 130 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 131 The participants can be started from the clamp repository by executing the following maven command from the appropriate directories.
 132 The participants will be started and get registered to the Control Loop runtime.
 133
 134 Navigate to the directory "participant/participant-impl/participant-impl-kubernetes/" and start kubernetes participant.
 135
 136 .. code-block:: bash
 137
 138     mvn spring-boot:run
 139
 140 Navigate to the directory "participant/participant-impl/participant-impl-http/" and start http participant.
 141
 142 .. code-block:: bash
 143
 144     mvn spring-boot:run
 145
 146
 147 3. Running Tests
 148 ****************
 149 In this section, we will run through the sequence of steps in Control Loop workflow . The workflow can be triggered via Postman client.
 150
 151 3.1 Commissioning
 152 =================
 153 Commission Control loop TOSCA definitions to Runtime.
 154
 155 The Control Loop definitions are commissioned to CL runtime which populates the CL runtime database.
 156 The following sample TOSCA template is commissioned to the runtime endpoint which contains definitions for kubernetes participant that deploys nginx ingress microservice
 157 helm chart and a http POST request for http participant.
 158
 159 :download:`Tosca Service Template <tosca/smoke-test-participants.yaml>`
 160
 161 Commissioning Endpoint:
 162
 163 .. code-block:: bash
 164
 165    POST: https://<CL Runtime IP> : <Port> /onap/controlloop/v2/commission
 166
 167 A successful commissioning gives 200 response in the postman client.
 168
 169
 170 3.2 Create New Instances of Control Loops
 171 =========================================
 172 Once the template is commissioned, we can instantiate Control Loop instances. This will create the instances with default state "UNINITIALISED".
 173
 174 Instantiation Endpoint:
 175
 176 .. code-block:: bash
 177
 178    POST: https://<CL Runtime IP> : <Port> /onap/controlloop/v2/instantiation
 179
 180 Request body:
 181
 182 :download:`Instantiation json <json/cl-instantiation.json>`
 183
 184 3.3 Change the State of the Instance
 185 ====================================
 186 When the Control loop is updated with state “PASSIVE”, the Kubernetes participant fetches the node template for all control loop elements and deploys the helm chart of each CL element in to the cluster. The following sample json input is passed on the request body.
 187
 188 Control Loop Update Endpoint:
 189
 190 .. code-block:: bash
 191
 192    PUT: https://<CL Runtime IP> : <Port> /onap/controlloop/v2/instantiation/command
 193
 194    Request body:
 195 .. code-block:: bash
 196
 197    {
 198      "orderedState": "PASSIVE",
 199      "controlLoopIdentifierList": [
 200        {
 201          "name": "K8SInstance0",
 202          "version": "1.0.1"
 203        }
 204      ]
 205    }
 206
 207
 208 After the state changed to "PASSIVE", nginx-ingress pod is deployed in the kubernetes cluster. And http participant should have posted the dummy data to the configured URL in the tosca template.
 209
 210 The following command can be used to verify the pods deployed successfully by kubernetes participant.
 211
 212 .. code-block:: bash
 213
 214    helm ls -n onap | grep nginx
 215    kubectl get po -n onap | grep nginx
 216
 217 The overall state of the control loop should be "PASSIVE" to indicate both the participants has successfully completed the operations. This can be verified by the following rest endpoint.
 218
 219 Verify control loop state:
 220
 221 .. code-block:: bash
 222
 223    GET: https://<CL Runtime IP> : <Port>/onap/controlloop/v2/instantiation
 224
 225
 226 3.4 Control Loop can be "UNINITIALISED" after deployment
 227 ========================================================
 228
 229 By changing the state to "UNINITIALISED", all the helm deployments under the corresponding control loop will be uninstalled from the cluster.
 230 Control Loop Update Endpoint:
 231
 232 .. code-block:: bash
 233
 234    PUT: https://<CL Runtime IP> : <Port> /onap/controlloop/v2/instantiation/command
 235
 236    Request body:
 237 .. code-block:: bash
 238
 239    {
 240      "orderedState": "UNINITIALISED",
 241      "controlLoopIdentifierList": [
 242        {
 243          "name": "K8SInstance0",
 244          "version": "1.0.1"
 245        }
 246      ]
 247    }
 248
 249 The nginx pod should be deleted from the k8s cluster.
 250
 251 This concludes the required smoke tests for http and kubernetes participants.