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 * Your local helm is in the location /usr/local/bin/helm
  25 * Your local kubectl is in the location /usr/local/bin/kubectl
  26
  27 The procedure documented in this article has been verified using Ubuntu 20.04 LTS VM.
  28
  29 2.1 Prerequisites
  30 =================
  31 - Java 17
  32 - Docker
  33 - Maven 3.9
  34 - Git
  35 - helm3
  36 - k8s cluster
  37 - Refer to this guide for basic environment setup `Setting up dev environment <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_
  38
  39 2.2 Cloning CLAMP automation composition
  40 ========================================
  41
  42 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.
  43
  44 .. code-block:: bash
  45
  46     cd ~/git
  47     git clone https://gerrit.onap.org/r/policy/clamp clamp
  48
  49
  50 Execution of the command above results in the following directory hierarchy in your *~/git* directory:
  51
  52     *  ~/git/clamp
  53
  54
  55 2.3 Setting up the components
  56 =============================
  57
  58 2.3.1 Running MariaDb and Kafka
  59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  60 We will be using Docker to run our mariadb instance and Kafka. It will have the acm-runtime database running in it.
  61 The easiest way to do this is to perform a SQL script. Create the *mariadb.sql* file in the directory *~/git*.
  62
  63 .. literalinclude:: files/mariadb.sql
  64    :language: SQL
  65
  66 Create the '*docker-compose.yaml*' using following code:
  67
  68 .. literalinclude:: files/docker-compose-local.yaml
  69    :language: yaml
  70
  71 Run the docker composition:
  72
  73    .. code-block:: bash
  74
  75       cd ~/git/
  76       docker compose up
  77
  78 2.3.2 Setting topicParameterGroup for kafka localhost
  79 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  80 It needs to set 'kafka' as topicCommInfrastructure and 'localhost:29092' as server.
  81 In the clamp repo, you should find the file 'runtime-acm/src/main/resources/application.yaml'. This file (in the 'runtime' parameters section) may need to be altered as below:
  82
  83 .. literalinclude:: files/runtime-application.yaml
  84    :language: yaml
  85
  86 Same changes (in the 'participant' parameters section)
  87 may need to be apply into the file 'participant/participant-impl/participant-impl-http/src/main/resources/config/application.yaml'.
  88
  89 .. literalinclude:: files/participant-http-application.yaml
  90    :language: yaml
  91
  92 And into the file 'participant/participant-impl/participant-impl-kubernetes/src/main/resources/config/application.yaml'.
  93
  94 .. literalinclude:: files/participant-kubernetes-application.yaml
  95    :language: yaml
  96
  97 If the helm location is not '/usr/local/bin/helm' or the kubectl location is not '/usr/local/bin/kubectl', you have to update
  98 the file 'participant/participant-impl/participant-impl-kubernetes/src/main/java/org/onap/policy/clamp/acm/participant/kubernetes/helm/HelmClient.java'.
  99
 100 2.3.3 Automation composition Runtime
 101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 102 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.
 103
 104 .. code-block:: bash
 105
 106     mvn spring-boot:run
 107
 108 2.3.4 Helm chart repository
 109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 110 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.
 111 The following command can be used to add nginx repository to the helm client.
 112
 113 .. code-block:: bash
 114
 115     helm repo add nginx-stable https://helm.nginx.com/stable
 116
 117 2.3.5 Kubernetes and http participants
 118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 119 The participants can be started from the clamp repository by executing the following maven command from the appropriate directories.
 120 The participants will be started and get registered to the Automation composition runtime.
 121
 122 Navigate to the directory "participant/participant-impl/participant-impl-kubernetes/" and start kubernetes participant.
 123
 124 .. code-block:: bash
 125
 126     mvn spring-boot:run
 127
 128 Navigate to the directory "participant/participant-impl/participant-impl-http/" and start http participant.
 129
 130 .. code-block:: bash
 131
 132     mvn spring-boot:run
 133
 134 For building docker images of runtime-acm and participants:
 135
 136 .. code-block:: bash
 137
 138    cd ~/git/onap/policy/clamp/
 139    mvn clean install -P docker
 140
 141
 142 3. Running Tests
 143 ****************
 144 In this section, we will run through the sequence of steps in ACM workflow . The workflow can be triggered via Postman client.
 145
 146 3.1 Commissioning
 147 =================
 148 Commission Automation composition TOSCA definitions to Runtime.
 149
 150 The Automation composition definitions are commissioned to runtime-acm which populates the ACM runtime database.
 151 The following sample TOSCA template is commissioned to the runtime endpoint which contains definitions for kubernetes participant that deploys nginx ingress microservice
 152 helm chart and a http POST request for http participant.
 153
 154 :download:`Tosca Service Template <tosca/smoke-test-participants.yaml>`
 155
 156 Commissioning Endpoint:
 157
 158 .. code-block:: bash
 159
 160    POST: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions
 161
 162 A successful commissioning gives 201 responses in the postman client.
 163
 164 3.2 Prime an Automation composition definition
 165 ==============================================
 166 Once the template is commissioned, we can prime it. This will connect AC definition with related participants.
 167
 168 Prime Endpoint:
 169
 170 .. code-block:: bash
 171
 172    PUT: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}
 173
 174 Request body:
 175
 176 .. code-block:: json
 177
 178    {
 179         "primeOrder": "PRIME"
 180    }
 181
 182 A successful prime request gives 202 responses in the postman client.
 183
 184 3.3 Create New Instances of Automation composition
 185 ==================================================
 186 Once AC definition is primes, we can instantiate automation composition instances. This will create the instances with default state "UNDEPLOYED".
 187
 188 Instantiation Endpoint:
 189
 190 .. code-block:: bash
 191
 192    POST: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}/instances
 193
 194 Request body:
 195
 196 :download:`Instantiation json <json/acm-instantiation.json>`
 197
 198 A successful creation of new instance gives 201 responses in the postman client.
 199
 200 3.4 Change the State of the Instance
 201 ====================================
 202 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.
 203
 204 Automation Composition Update Endpoint:
 205
 206 .. code-block:: bash
 207
 208    PUT: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}
 209
 210    Request body:
 211 .. code-block:: bash
 212
 213    {
 214     "deployOrder": "DEPLOY"
 215    }
 216
 217
 218 A successful deploy request gives 202 responses in the postman client.
 219 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.
 220
 221 The following command can be used to verify the pods deployed successfully by kubernetes participant.
 222
 223 .. code-block:: bash
 224
 225    helm ls -n onap | grep nginx
 226    kubectl get po -n onap | grep nginx
 227
 228 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.
 229
 230 Verify automation composition state:
 231
 232 .. code-block:: bash
 233
 234    GET: https://<Runtime ACM IP> : <Port>/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}
 235
 236
 237 3.5 Automation Compositions can be "UNDEPLOYED" after deployment
 238 ================================================================
 239
 240 By changing the state to "UNDEPLOYED", all the helm deployments under the corresponding automation composition will be uninstalled from the cluster.
 241 Automation Composition Update Endpoint:
 242
 243 .. code-block:: bash
 244
 245    PUT: https://<Runtime ACM IP> : <Port> /onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}
 246
 247    Request body:
 248 .. code-block:: bash
 249
 250    {
 251     "deployOrder": "UNDEPLOY"
 252    }
 253
 254 The nginx pod should be deleted from the k8s cluster.
 255
 256 This concludes the required smoke tests for http and kubernetes participants.