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