Add validaton tests for KNI
[validation.git] / ui / README.rst
1
2 Akraino Blueprint Validation UI
3 ========
4
5 Introduction
6 ------------
7
8 This project contains the source code of the Akraino Blueprint Validation UI. It is based on the ONAP portal SDK, version 2.4.0. It should be noted that the copyright of all the files of the aforementioned project that were left intact, has not been changed.
9
10 This UI consists of the front-end and back-end parts.
11
12 The front-end part is based on HTML, CSS, and AngularJS technologies. The back-end part is based on Spring MVC and Apache Tomcat technologies.
13
14 Based on these instructions, a user can provide the prerequisites, compile the source code and deploy the UI.
15
16 Scope
17 -----
18
19 The blueprint validation UI aims to be hosted by LF servers and will be exposed using public IP and domain names.
20
21 It provides a user-friendly way for displaying blueprints validation test results. Based on these results, the status of a blueprint can be determined (mature, incubation state, etc.).
22
23 In specific, the purpose of the UI is twofold:
24
25 1) Support full control loop of producing results. In this mode, the UI must be connected with a Jenkins instance capable of running blueprint validation tests.
26    It will enable the user to define a blueprint for validation using its name, version, layer, desired lab and desired timeslot. This data constitutes a submission. It should be noted that the blueprint family is derived from the blueprint name.
27    Also, the UI will have the ability to track the lifecycle of a submission. A submission state can be one of the following: submitted, waiting, running and completed. The implementation vehicle for this action is the REST API of Jenkins.
28    Moreover, the UI must be connected with a mysql instance and the Nexus server where the results are stored.
29    Then, it will be able to trigger the appropriate job in Jenkins and receive the corresponding results from Nexus.
30    Note that it makes no difference whether the Jenkins instance is the community one or a private one.
31 2) Partial control of producing results. In this mode, the UI must be connected with a mysql instance and the Nexus server where the results are stored.
32    Every blueprint owner is responsible of executing tests and storing results in Nexus using his/her own Jenkins instance. The UI only retrieves results from Nexus and displays them.
33
34 In both modes, user authentication, authorization and accounting (AAA) will be supported in order to control access to resources, enforce policies on these resources and audit their usage.
35
36 Prerequisites:
37 ~~~~~~~~~~~~~~
38
39 In order for the blueprint validation UI to be functional, the following items are taken for granted:
40
41 - An appropriate mysql instance is up and running (look at the Database subsection).
42   This prerequisite concerns both of the UI modes.
43
44 - The available labs and their silos (i.e. which silo is used by a lab in order to store results in Nexus) for blueprint validation execution are stored in mysql (look at the Database subsection). It is the lab owner's responsibility to update them using the UI.
45   This prerequisite concerns both the partial and the full control loop modes.
46
47 - The available timeslots for blueprint validation execution of every lab are stored in the mysql (look at the Database subsection). It is the lab owner's responsibility to update them using the UI.
48   This prerequisite concerns only the full control loop mode.
49
50 - The data of available blueprints (i.e. blueprint name) is stored in the mysql database (look at the Database subsection). This data is automatically updated by the UI using info from Nexus. If a blueprint owner's is not satisfied with this info, he/her must update it using the UI.
51   This prerequisite concerns only the full control loop mode.
52
53 - The data of an available blueprint instance for validation (i.e. version and layer) is stored in the mysql database (look at the Database subsection). This data is automatically updated by the UI using info from Nexus. If a blueprint owner's is not satisfied with this info, he/her must update it using the UI.
54   This prerequisite concerns only the full control loop mode.
55
56 - A Jenkins instance exists capable of executing blueprint validation tests on the specified lab and storing the results to Nexus server (look at the Jenkins configuration subsection).
57   Also, this data is updated using info from results fetched from Nexus. This prerequisite concerns only the full control loop mode.
58
59 - A Nexus server exists where all the blueprint validation results are stored (look at the Nexus subsection).
60   This prerequisite concerns both of the UI modes.
61
62 - The whole installation and deployment of a blueprint and its corresponding blueprint family components (i.e. the appropriate edge cloud stack with its combination of infrastructure hardware components, OS, K8s, software, etc) are already performed in the appropriate lab.
63   Recall that multiple labs can be used for a specific blueprint validation. Also, it is the responsibility of the blueprint submitter to ensure that the edge validation and community CI labs can support comprehensive validation of the blueprint and cover all use case characteristics.
64   This prerequisite concerns both of the UI modes.
65
66 Developer's guide
67 -----------------
68
69 Download the project
70 ~~~~~~~~~~~~~~~~~~~~
71
72 .. code-block:: console
73
74     git clone "https://gerrit.akraino.org/r/validation"
75
76 Prerequisites
77 ~~~~~~~~~~~~~
78
79 - Tools
80
81 In order to setup the development environment, the following tools are needed:
82 - JDK 1.8
83 - Maven
84 - docker
85 - MySQL client
86
87 Execute the commands below in order to install these tools (note that the PROXY_IP and PROXY_PORT variables must be substituted with the ones that are used by the hosting operating system)
88
89 If the host is behind a proxy, define this proxy using the following commands:
90
91 .. code-block:: console
92     sudo touch /etc/apt/apt.conf.d/proxy.conf
93     sudo sh -c 'echo "Acquire::http::proxy \"http://<PROXY_IP>:<PROXY_PORT>/\";" >> /etc/apt/apt.conf.d/proxy.conf'
94     sudo sh -c 'echo "Acquire::https::proxy \"https://<PROXY_IP>:<PROXY_PORT>/\";" >> /etc/apt/apt.conf.d/proxy.conf'
95     sudo sh -c 'echo "Acquire::ftp::proxy \"ftp://<PROXY_IP>:<PROXY_PORT>/\";" >> /etc/apt/apt.conf.d/proxy.conf'
96     sudo apt-get update
97     export http_proxy=http://<PROXY_IP>:<PROXY_PORT>
98     export https_proxy=http://<PROXY_IP>:<PROXY_PORT>
99
100 Install jdk and maven using the following commands:
101
102 .. code-block:: console
103     sudo apt install default-jdk
104     sudo apt install maven
105
106 If the host is behind a proxy, configure this proxy for maven:
107
108 .. code-block:: console
109     nano ~/.m2/settings.xml
110     <Paste the following lines>
111
112     <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
113      <proxies>
114       <proxy>
115        <active>true</active>
116        <protocol>http</protocol>
117        <host><PROXY_IP></host>
118        <port><PROXY_PORT></port>
119        <nonProxyHosts>127.0.0.1|localhost</nonProxyHosts>
120       </proxy>
121       <proxy>
122        <id>https</id>
123        <active>true</active>
124        <protocol>https</protocol>
125        <host><PROXY_IP></host>
126        <port><PROXY_PORT></port>
127        <nonProxyHosts>127.0.0.1|localhost</nonProxyHosts>
128       </proxy>
129      </proxies>
130     </settings>
131
132     <Save and exit from nano>
133
134 Install docker using the following commands:
135
136 .. code-block:: console
137     sudo apt install docker.io
138     sudo groupadd docker
139     sudo gpasswd -a $USER docker
140     newgrp docker
141
142 If the host is behind a proxy, configure docker to use this proxy:
143
144 .. code-block:: console
145     mkdir /etc/systemd/system/docker.service.d
146     sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
147     <Paste the following lines>
148
149     [Service]
150     Environment="HTTP_PROXY=http://<PROXY_IP>:<PROXY_PORT>/"
151
152     <Save and exit from nano>
153
154     sudo systemctl daemon-reload
155     sudo systemctl restart docker
156
157 Install mySQL client:
158
159 .. code-block:: console
160     sudo apt install mysql-client
161
162 - Database
163
164 A mysql database instance is needed for both modes of the UI with the appropriate databases and tables in order for the back-end system to store and retrieve data.
165
166 The pom.xml file supports the creation of an appropriate docker image for development purposes. The initialization scripts reside under the db-scripts directory.
167
168 Also, a script has been developed, namely validation/docker/mysql/deploy.sh which easily deploys the container. This script accepts the following items as input parameters:
169
170 CONTAINER_NAME, name of the container, default value is akraino-validation-mysql
171 MYSQL_ROOT_PASSWORD, the desired mysql root user password, this variable is required
172 MYSQL_USER, the mysql user, the default value is 'akraino'
173 MYSQL_PASSWORD, the desired mysql user password, this variable is required
174 REGISTRY, registry of the mysql image, default value is akraino
175 NAME, name of the mysql image, default value is validation
176 TAG_PRE, first part of the image version, default value is mysql
177 TAG_VER, last part of the image version, default value is latest
178
179 In order to build and deploy the image using only the required parameters, the below instructions should be followed:
180
181 The mysql root password and the mysql user password (currently the UI connects to the database using the akraino user) should be configured using the appropriate variables and the following commands should be executed (the user should override default variables based on requirements):
182
183 .. code-block:: console
184
185     cd validation/ui
186     mvn docker:build -Ddocker.filter=akraino/validation:dev-mysql-latest
187     cd ../docker/mysql
188     ./deploy.sh --TAG_PRE dev-mysql --MYSQL_ROOT_PASSWORD <mysql root user password> --MYSQL_PASSWORD <mysql akraino user password>
189     mysql -p<MYSQL_AKRAINO_PASSWORD> -uakraino -h <IP of the mysql container> < ../../ui/db-scripts/examples/initialize_db_example.sql
190
191 In order to retrieve the IP of the mysql container, the following command should be executed:
192
193 .. code-block:: console
194
195     docker inspect <name of the mysql container>
196
197 Furthermore, the TAG_PRE variable should be defined because the default value is 'mysql' (note that the 'dev-mysql' is used for development purposes - look at pom.xml file).
198
199 If the database must be re-deployed (it is assumed that the corresponding mysql container has been stopped and deleted) while the persistent storage already exists (currently, the 'akraino-validation-mysql' docker volume is used), a different approach should be used after the image building process.
200
201 To this end, another script has been developed, namely validation/docker/mysql/deploy_with_existing_storage.sh which easily deploys the container. This script accepts the following as input parameters:
202
203 CONTAINER_NAME, the name of the container, default value is akraino-validation-mysql
204 REGISTRY, the registry of the mysql image, default value is akraino
205 NAME, the name of the mysql image, default value is validation
206 TAG_PRE, the first part of the image version, default value is mysql
207 TAG_VER, the last part of the image version, default value is latest
208
209 In order to deploy the image using only the required parameters and the existing persistent storage, the below instructions should be followed (the user should override the default variables based on the requirements):
210
211 .. code-block:: console
212
213     cd validation/docker/mysql
214     ./deploy_with_existing_persistent_storage.sh --TAG_PRE dev-mysql
215
216 Finally, if the database must be re-deployed (it is assumed that the corresponding mysql container has been stopped and deleted) and the old persistent storage must be deleted, the used docker volume should be first deleted (note that all database's data will be lost).
217
218 To this end, after the image build process, the following commands should be executed (the user should override the default variables based on the requirements):
219
220 .. code-block:: console
221
222     docker volume rm akraino-validation-mysql
223     cd validation/docker/mysql
224     ./deploy.sh --TAG_PRE dev-mysql --MYSQL_ROOT_PASSWORD <root user password> --MYSQL_PASSWORD <mysql akraino user password>
225     mysql -p<MYSQL_AKRAINO_PASSWORD> -uakraino -h <IP of the mysql container> < ../../ui/db-scripts/examples/initialize_db_example.sql
226
227 In the context of the UI application, the following tables exist in the database:
228
229 - lab (here, every lab owner should store the name of the lab and the silo used for storing results in Nexus)
230 - timeslot (here, every lab owner should register the available timeslots that can be used for blueprint validation test execution)
231 - blueprint_layer (here, all the blueprint layers should be registered. These layers will be referenced by the blueprint instances)
232 - blueprint (here, every blueprint owner should register the name of the blueprint)
233 - blueprint_instance_for_validation (here, every blueprint owner should register the blueprint instances for validation, i.e. version and layer)
234 - blueprint_instance_blueprint_layer (here, the many-to-many relationship between blueprint instances and layers is formulated)
235 - blueprint_instance_timeslot (here, the many-to-many relationship between blueprint instances and timeslots is formulated)
236
237 As it has been already mentioned, a user can perform CRUD operations on these tables using the UI. Also, all these tables except from lab and timeslot are initialized and updated automatically
238 by the UI by fetching data from Nexus. It is the lab owners responsibility to update them if a modifications is needed (especially the data related to lab and timeslot tables).
239
240 An example of data initialization is stored in the following file:
241
242     db-scripts/examples/initialize_db_example.sql
243
244 That is the reason why the command 'mysql -p<MYSQL_AKRAINO_PASSWORD> -uakraino -h <IP of the mysql container> < ../../ui/db-scripts/examples/initialize_db_example.sql' has been used previously.
245
246 Some of this data is illustrated below:
247
248 .. code-block:: console
249
250     Labs:
251     id:1, lab:'att', silo:'att-blu-val'
252
253     Timeslots:
254     id:1 , start date and time: 'now', duration: null, lab: 1
255
256     Blueprint layers:
257     id:1, layer: 'hardware';
258
259     Blueprints:
260     id: 2 , blueprint_name : 'rec'
261
262     Blueprint Instances:
263     id: 2, blueprint_id: 2 (i.e. rec), version: "master"
264
265     blueprint_instances_blueprint_layers
266     blueprint_id: 2 (i.e. rec), layer_id: 1 (i.e. hardware)
267
268     blueprint_instances_timeslots
269     blueprint_instance_id: 2 (i.e. rec), timeslot_id: 1 (i.e. now in att lab)
270
271 It should be noted that currently the start date and time and the duration of the timeslot are not taken into account by the UI (see limitation section). Therefore, a user should define 'now' and null respectively for their content.
272
273 Based on this data, the UI enables the user to select an appropriate blueprint instance for validation.
274
275 In the following lines it is explained how a user can update database using the mysql tool. However, it is advised that UI should be used for this purpose as it supports a more user-friendly way.
276
277 For example, if a user wants to define a new lab with the following data:
278
279     lab: community, silo : 'community'
280
281 the following file should be created:
282
283 name: dbscript
284 content:
285     SET FOREIGN_KEY_CHECKS=1;
286     use akraino_bluvalui;
287     insert into lab (id, lab, silo) values(2, 'community', 'community');
288
289 Then, the following command should be executed:
290
291 .. code-block:: console
292
293     mysql -p<MYSQL_AKRAINO_PASSWORD> -uakraino -h <IP of the mysql container> < ./dbscript.sql
294
295 For example, if a user wants to define a new timeslot with the following data:
296
297     start date and time:'now', duration: 0, lab: AT&T
298
299 the following file should be created:
300
301 name: dbscript
302 content:
303     SET FOREIGN_KEY_CHECKS=1;
304     use akraino_bluvalui;
305     insert into timeslot values(2, 'now', null, 2);
306
307 2 is the id of the community lab.
308
309 Then, the following command should be executed:
310
311 .. code-block:: console
312
313     mysql -p<MYSQL_AKRAINO_PASSWORD> -uakraino -h <IP of the mysql container> < ./dbscript.sql
314
315 Furthermore, if a user wants to define a new blueprint, namely "newBlueprint", and an instance of this blueprint with version "master" and layer "k8s" and assign a timeslot to it, the following file should be created:
316
317 name: dbscript
318 content:
319     SET FOREIGN_KEY_CHECKS=1;
320     use akraino_bluvalui;
321     insert into blueprint (id, blueprint_name) values(3, 'newBlueprint');
322     insert into blueprint_instance (id, blueprint_id, version) values(3, 3, 'master');
323     insert into blueprint_layer (id, layer) values(4, 'k8s');
324     insert into blueprint_instance_blueprint_layer (blueprint_instance_id, blueprint_layer_id) values(3, 4);
325     insert into blueprint_instance_timeslot (blueprint_instance_id, timeslot_id) values(3, 2);
326
327 Then, the following command should be executed:
328
329 .. code-block:: console
330
331     mysql -p<MYSQL_AKRAINO_PASSWORD> -uakraino -h <IP of the mysql container> < ./dbscript.sql
332
333 The UI will automatically retrieve this new data and display it to the user.
334
335 - Jenkins Configuration
336
337 Recall that for full control loop, a Jenkins instance is needed capable of executing blueprint validation tests to the specified lab. The Blueprint validation UI will trigger job executions in that instance.
338
339 It should be noted that it is not the UI responsibility to deploy a Jenkins instance.
340
341 Furthermore, this instance must have the following option enabled: "Manage Jenkins -> Configure Global Security -> Prevent Cross Site Request Forgery exploits".
342
343 Also, currently, the corresponding Jenkins job should accept the following as input parameters: "SUBMISSION_ID", "BLUEPRINT", "VERSION", "LAYER", "OPTIONAL", "LAB" and "UI_IP".
344 The "SUBMISSION_ID" and "UI_IP" parameters (i.e. IP address of the UI host machine-this is needed by the Jenkins instance in order to send back Job completion notification) are created and provided by the back-end part of the UI.
345 The "BLUEPRINT", "VERSION", "LAYER" and "LAB" parameters are configured by the UI user. The parameter "OPTIONAL" defines whether the optional test cases should be included or not.
346
347 Moreover, as the Jenkins notification plugin (https://wiki.jenkins.io/display/JENKINS/Notification+Plugin) seems to ignore proxy settings, the corresponding Jenkins job must be configured to execute the following commands at the end (Post-build Actions)
348
349 TBD
350
351 - Nexus server
352
353 All the blueprint validation results are stored in Nexus server for both modes of the UI.
354
355 It should be noted that it is not the UI responsibility to deploy a Nexus server.
356
357 These results must be available in the following url:
358
359     https://nexus.akraino.org/content/sites/logs/<lab_silo>/bluval_results/<Blueprint name>/<Blueprint version>/<timestamp>/results/<layer>/<name_of_the_test_suite>
360
361 where <lab_silo> is the silo used by a lab for storing results in Nexus (for example 'att-blu-val'), <Blueprint name> is the name of the blueprint, <Blueprint version> the the blueprint version, <timestamp> is the timestamp used for producinf the results, <layer> is the blueprint layer and <name_of_the_test_suite> is the name of the corresponding test suite.
362
363 Below, an example URL is illustrated
364
365    https://nexus.akraino.org/content/sites/logs/att-blu-val/bluval_results/rec/master/20190611-132818/results/hardware/bios_version/
366
367 Moreover, the results should be stored in the 'output.xml' file and placed in the aforementioned URL.
368
369 Compiling
370 ~~~~~~~~~
371
372 .. code-block:: console
373
374     cd validation/ui
375     mvn clean package
376
377 Deploying
378 ~~~~~~~~~
379
380 The pom.xml file supports the building of an appropriate container image using the produced war file.
381
382 In order to build the image, the following commands should be executed:
383
384 .. code-block:: console
385
386     cd validation/ui
387     mvn docker:build -Ddocker.filter=akraino/validation:dev-ui-latest
388
389 Also, a script has been developed, namely validation/docker/ui/deploy.sh which easily deploys the container. This script accepts the following as input parameters:
390
391 CONTAINER_NAME, the name of the container, default value is akraino-validation-ui
392 DB_IP_PORT, the IP and port of the mysql instance, this variable is required
393 MYSQL_USER, the mysql user, the default value is 'akraino'
394 MYSQL_PASSWORD, the mysql user password, this variable is required
395 REGISTRY, the registry of the ui image, default value is akraino
396 NAME, the name of the ui image, default value is validation
397 TAG_PRE, the first part of the image version, default value is ui
398 TAG_VER, the last part of the image version, default value is latest
399 JENKINS_URL, the URL of the Jenkins instance (http or https must be defined), the default value is 'https://jenkins.akraino.org/'
400 JENKINS_USERNAME, the Jenkins user name, the default value is 'demo' (in the context of UI full control loop mode, this parameter must be changed to include a real Jenkins user)
401 JENKINS_USER_PASSWORD, the Jenkins user password, the default value is 'demo' (in the context of UI full control loop mode, this parameter must be changed to include a real Jenkins user password)
402 JENKINS_JOB_NAME, the name of Jenkins job capable of executing the blueprint validation tests, the default value is 'validation' (in the context of UI full control loop mode, this parameter must be changed to include a real Jenkins job name)
403 NEXUS_PROXY, the needed proxy in order for the Nexus server to be reachable, default value is none
404 JENKINS_PROXY, the needed proxy in order for the Jenkins server to be reachable, default value is none
405 CERTDIR, the directory where the SSL certificates can be found, default value is the working directory where self signed certificates exist only for demo purposes
406 ENCRYPTION_KEY, the key that should be used by the AES algorithm for encrypting passwords stored in database, this variable is required
407 UI_ADMIN_PASSWORD, the desired Blueprint Validation UI password for the admin user, this variable is required
408 TRUST_ALL, the variable that defines whether the UI should trust all certificates or not, default value is false
409 USE_NETWORK_HOST, the variable that defines whether the UI container should run in 'network host' mode or not, default value is "false"
410
411 So, for a functional UI, the following prerequisites are needed:
412
413 - The mysql container in up and running state
414 - A Jenkins instance capable of running the blueprint validation test (this is optional and is needed only for UI full control loop mode)
415 - A Nexus repo in which all the test results are stored.
416
417 Then, the following commands can be executed in order to deploy the UI container (the user should override the default variables based on requirements):
418
419 .. code-block:: console
420     cd ../docker/ui
421     ./deploy.sh --TAG_PRE dev-ui --DB_IP_PORT <IP and port of the mysql> --MYSQL_PASSWORD <mysql akraino password> --ENCRYPTION_KEY <encryption key> --UI_ADMIN_PASSWORD <UI admin user password>
422
423 The content of the DB_IP_PORT can be for example '172.17.0.3:3306'. Also, the value of the encryption key can be for example 'AGADdG4D04BKm2IxIWEr8o=='.
424
425 Currently, one user is supported by the UI, namely admin (full privileges). Its password is initialized during UI deployment. This password can be modified using the UI. Furthermore, more users can be created/modified using the UI.
426
427 Furthermore, the TAG_PRE variable should be defined as the default value is 'ui' (note that the 'dev-ui' is used for development purposes - look at pom.xml file).
428
429 If no proxy exists, the proxy ip and port variables should not be defined.
430
431 More users can be created using the 'Create User' tab of the UI. This tab is available only for the admin user.
432
433 If the content of the 'USE_NETWORK_HOST' is equal to true (in this case, the ports 8443 and 443 must be available on the host), the UI should be available in the following url:
434
435     https://<IP of the host>
436
437 Else, the UI should be available in the following url:
438
439     https://<IP of the UI container>
440
441 As far as the SSL certificates are concerned, self-signed built-in certificates exist in the 'validation/docker/ui' directory which are used by default. It should be noted that these
442 certificates should be used only for demo purposes. If a user wants to use different ones which are more appropriate for a production environment, the directory that contains these new
443 certificates must be defined using the 'CERTDIR' parameter of the 'validation/docker/ui/deploy.sh' script. It should be noted that the certificates must have specific names, that are 'bluval.crt'
444 and 'bluval.key' for the certificate and the key respectively.
445
446 User's guide
447 -----------------
448 TBD
449
450 Limitations
451 -----------
452 - The UI has been tested using Chrome and Firefox browsers.
453 - The back-end part of the UI does not take into account the start date and time and duration of the configured timeslot. It immediately triggers the corresponding Jenkins Job.