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

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-acm-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 Automation Composition Management 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
  48 In this setup guide, we will be setting up all the components technically required for a working dev environment.
  49
  50 2.3 Setting up the components
  51 =============================
  52
  53 2.3.1 MariaDB Setup
  54 ^^^^^^^^^^^^^^^^^^^
  55 We will be using Docker to run our mariadb instance. It will have the acm-runtime database running in it.
  56
  57 - AutomationComposition: the runtime-acm db
  58
  59 The easiest way to do this is to perform a SQL script. Create the *mariadb.sql* file in the directory *~/git*.
  60
  61 .. code-block:: mysql
  62
  63     CREATE DATABASE `clampacm`;
  64     USE `clampacm`;
  65     CREATE USER 'policy';
  66     GRANT ALL on clampacm.* to 'policy' identified by 'P01icY' with GRANT OPTION;
  67
  68 Execution of the command above results in the creation and start of the *mariadb-smoke-test* container.
  69
  70     .. code-block:: bash
  71
  72        cd ~/git
  73        docker run --name mariadb-smoke-test  \
  74         -p 3306:3306 \
  75         -e MYSQL_ROOT_PASSWORD=my-secret-pw  \
  76         --mount type=bind,source=$HOME/git/mariadb.sql,target=/docker-entrypoint-initdb.d/data.sql \
  77         -d mariadb:10.10.2 \
  78         --lower-case-table-names=1
  79
  80 The database will be exposed locally on port 3306 and will be backed by an anonymous docker volume.
  81
  82 2.3.2 DMAAP Simulator
  83 ^^^^^^^^^^^^^^^^^^^^^
  84 For convenience, a dmaap simulator has been provided in the policy/models repository. To start the simulator, you can do the following:
  85
  86 1. Navigate to /models-sim/policy-models-simulators in the policy/models repository.
  87 2. Add a configuration file to src/test/resources with the following contents:
  88
  89 .. code-block:: json
  90
  91     {
  92        "dmaapProvider":{
  93           "name":"DMaaP simulator",
  94           "topicSweepSec":900
  95        },
  96        "restServers":[
  97           {
  98              "name":"DMaaP simulator",
  99              "providerClass":"org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1",
 100              "host":"localhost",
 101              "port":3904,
 102              "https":false
 103           }
 104        ]
 105     }
 106
 107 3. You can then start dmaap with:
 108
 109 .. code-block:: bash
 110
 111     mvn exec:java  -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/YOUR_CONF_FILE.json"
 112
 113 At this stage the dmaap simulator should be running on your local machine on port 3904.
 114
 115
 116 2.3.3 Automation composition Runtime
 117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 118 To start the automation composition runtime service, we need to execute the following maven command from the "runtime-acm" directory in the clamp repo. Automation composition runtime uses the config file "src/main/resources/application.yaml" by default.
 119
 120 .. code-block:: bash
 121
 122     mvn spring-boot:run
 123
 124 2.3.4 Helm chart repository
 125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 126 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.
 127 The following command can be used to add nginx repository to the helm client.
 128
 129 .. code-block:: bash
 130
 131     helm repo add nginx-stable https://helm.nginx.com/stable
 132
 133 2.3.5 Kubernetes and http participants
 134 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 135 The participants can be started from the clamp repository by executing the following maven command from the appropriate directories.
 136 The participants will be started and get registered to the Automation composition runtime.
 137
 138 Navigate to the directory "participant/participant-impl/participant-impl-kubernetes/" and start kubernetes participant.
 139
 140 .. code-block:: bash
 141
 142     mvn spring-boot:run
 143
 144 Navigate to the directory "participant/participant-impl/participant-impl-http/" and start http participant.
 145
 146 .. code-block:: bash
 147
 148     mvn spring-boot:run
 149
 150 For building docker images of runtime-acm and participants:
 151
 152 .. code-block:: bash
 153
 154    cd ~/git/onap/policy/clamp/packages/
 155    mvn clean install -P docker
 156
 157
 158 3. Running Tests
 159 ****************
 160 In this section, we will run through the sequence of steps in ACM workflow . The workflow can be triggered via Postman client.
 161
 162 3.1 Commissioning
 163 =================
 164 Commission Automation composition TOSCA definitions to Runtime.
 165
 166 The Automation composition definitions are commissioned to runtime-acm which populates the ACM runtime database.
 167 The following sample TOSCA template is commissioned to the runtime endpoint which contains definitions for kubernetes participant that deploys nginx ingress microservice
 168 helm chart and a http POST request for http participant.
 169
 170 :download:`Tosca Service Template <tosca/smoke-test-participants.yaml>`
 171
 172 Commissioning Endpoint:
 173
 174 .. code-block:: bash
 175
 176    POST: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions
 177
 178 A successful commissioning gives 201 responses in the postman client.
 179
 180 3.2 Prime an Automation composition definition
 181 ==============================================
 182 Once the template is commissioned, we can prime it. This will connect AC definition with related participants.
 183
 184 Prime Endpoint:
 185
 186 .. code-block:: bash
 187
 188    PUT: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}
 189
 190 Request body:
 191
 192 .. code-block:: json
 193
 194    {
 195         "primeOrder": "PRIME"
 196    }
 197
 198 3.3 Create New Instances of Automation composition
 199 ==================================================
 200 Once AC definition is primes, we can instantiate automation composition instances. This will create the instances with default state "UNDEPLOYED".
 201
 202 Instantiation Endpoint:
 203
 204 .. code-block:: bash
 205
 206    POST: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}/instances
 207
 208 Request body:
 209
 210 :download:`Instantiation json <json/acm-instantiation.json>`
 211
 212 3.4 Change the State of the Instance
 213 ====================================
 214 When the automation composition is updated with state “DEPLOYED”, the Kubernetes participant fetches the node template for all automation composition elements and deploys the helm chart of each AC element into the cluster. The following sample json input is passed on the request body.
 215
 216 Automation Composition Update Endpoint:
 217
 218 .. code-block:: bash
 219
 220    PUT: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}
 221
 222    Request body:
 223 .. code-block:: bash
 224
 225    {
 226     "deployOrder": "DEPLOY"
 227    }
 228
 229
 230 After the state changed to "DEPLOYED", 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.
 231
 232 The following command can be used to verify the pods deployed successfully by kubernetes participant.
 233
 234 .. code-block:: bash
 235
 236    helm ls -n onap | grep nginx
 237    kubectl get po -n onap | grep nginx
 238
 239 The overall state of the automation composition should be "DEPLOYED" to indicate both the participants has successfully completed the operations. This can be verified by the following rest endpoint.
 240
 241 Verify automation composition state:
 242
 243 .. code-block:: bash
 244
 245    GET: https://<Runtime ACM IP> : <Port>/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}
 246
 247
 248 3.4 Automation Compositions can be "UNDEPLOYED" after deployment
 249 ================================================================
 250
 251 By changing the state to "UNDEPLOYED", all the helm deployments under the corresponding automation composition will be uninstalled from the cluster.
 252 Automation Composition Update Endpoint:
 253
 254 .. code-block:: bash
 255
 256    PUT: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}
 257
 258    Request body:
 259 .. code-block:: bash
 260
 261    {
 262     "deployOrder": "UNDEPLOY"
 263    }
 264
 265 The nginx pod should be deleted from the k8s cluster.
 266
 267 This concludes the required smoke tests for http and kubernetes participants.