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 mariadb 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 mariadb 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 Currently, the partial control loop is not supported.
  35
  36 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.
  37
  38 Prerequisites:
  39 ~~~~~~~~~~~~~~
  40
  41 In order for the blueprint validation UI to be functional, the following items are taken for granted:
  42
  43 - An appropriate mariadb instance is up and running (look at the Database subsection).
  44   This prerequisite concerns both of the UI modes.
  45
  46 - The available labs for blueprint validation execution are defined by the corresponding lab owners (look at the Database subsection). It is their responsibility to publish them. Currently, this data is statically stored in the blueprint validation UI mariadb database. In order for a lab owner to update them, he/her must update the corresponding table entries. This inconvenience will be handled in the future.
  47   This prerequisite concerns only the full control loop mode.
  48
  49 - The available timeslots for blueprint validation execution of every lab are defined by the corresponding lab owners (look at the Database subsection). It is their responsibility to publish them. Currently, this data is statically stored in the blueprint validation UI mariadb database. In order for a lab owner to update them, he/her must update the corresponding table entries. This inconvenience will be handled in the future.
  50   This prerequisite concerns only the full control loop mode.
  51
  52 - The data of the lab silos (i.e. which silo is used by a lab in order to store results in Nexus) is stored in the mariadb database (look at the Database subsection). It is the blueprint owner's responsibility to publish it. Currently, this data is statically stored in the blueprint validation UI mariadb database. In order for a blueprint owner to update it, he/her must update the corresponding table entries. This inconvenience will be handled in the future.
  53   This prerequisite concerns only the full control loop mode.
  54
  55 - The data of available blueprints (i.e. blueprint name) is stored in the mariadb database (look at the Database subsection). It is the blueprint owner's responsibility to publish it. Currently, this data is statically stored in the blueprint validation UI mariadb database. In order for a blueprint owner to update it, he/her must update the corresponding table entries. This inconvenience will be handled in the future.
  56   This prerequisite concerns only the full control loop mode.
  57
  58 - The data of an available blueprint instance for validation (i.e. version, layer and description of the layer) is stored in the mariadb database (look at the Database subsection). It is the blueprint owner's responsibility to publish it. Currently, this data is statically stored in the blueprint validation UI mariadb database. In order for a blueprint owner to update it, he/her must update the corresponding table entries. This inconvenience will be handled in the future.
  59   This prerequisite concerns only the full control loop mode.
  60
  61 - 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).
  62   This prerequisite concerns only the full control loop mode.
  63
  64 - A Nexus server exists where all the blueprint validation results are stored (look at the Nexus subsection).
  65   This prerequisite concerns both of the UI modes.
  66
  67 - 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.
  68   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.
  69   This prerequisite concerns both of the UI modes.
  70
  71 Developer's guide
  72 -----------------
  73
  74 Download the project
  75 ~~~~~~~~~~~~~~~~~~~~
  76
  77 .. code-block:: console
  78
  79     git clone "https://gerrit.akraino.org/r/validation"
  80
  81 Prerequisites
  82 ~~~~~~~~~~~~~
  83
  84 - Database
  85
  86 A mariadb 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.
  87
  88 The pom.xml file supports the creation of an appropriate docker image for development purposes. The initialization scripts reside under the db-scripts directory.
  89
  90 Also, a script has been developed, namely validation/docker/mariadb/deploy.sh which easily deploys the container. This script accepts the following items as input parameters:
  91
  92 CONTAINER_NAME, name of the container, default value is akraino-validation-mariadb
  93 MARIADB_ROOT_PASSWORD, the desired mariadb root user password, this variable is required
  94 UI_ADMIN_PASSWORD, the desired Blueprint Validation UI password for the admin user, this variable is required
  95 UI_AKRAINO_PASSWORD, the desired Blueprint Validation UI password for the akraino user, this variable is required
  96 REGISTRY, registry of the mariadb image, default value is akraino
  97 NAME, name of the mariadb image, default value is validation
  98 TAG_PRE, first part of the image version, default value is mariadb
  99 TAG_VER, last part of the image version, default value is latest
 100 MARIADB_HOST_PORT, port on which mariadb is exposed on host, default value is 3307
 101
 102 Currently, two users are supported for the UI, namely admin (full privileges) and akraino (limited privileges). Their passwords must be defined in the database.
 103
 104 In order to build and deploy the image using only the required parameters, the below instructions should be followed:
 105
 106 The mariadb root user password (currently the UI connects to the database using root privileges), the UI admin password and the UI akraino password should be configured using the appropriate variables and the following commands should be executed:
 107
 108 .. code-block:: console
 109
 110     cd validation/ui
 111     mvn docker:build -Ddocker.filter=akraino/validation:dev-mariadb-latest
 112     cd ../docker/mariadb
 113     ./deploy.sh TAG_PRE=dev-mariadb MARIADB_ROOT_PASSWORD=<root user password> UI_ADMIN_PASSWORD=<UI admin user password> UI_AKRAINO_PASSWORD=<UI akraino user password>
 114     mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ../../ui/db-scripts/examples/initialize_db_example.sql
 115
 116 In order to retrieve the IP of the mariadb container, the following command should be executed:
 117
 118 .. code-block:: console
 119
 120     docker inspect <name of the mariadb container>
 121
 122 Furthermore, the TAG_PRE variable should be defined because the default value is 'mariadb' (note that the 'dev-mariadb' is used for development purposes - look at pom.xml file).
 123
 124 If the database must be re-deployed (it is assumed that the corresponding mariadb container has been stopped and deleted) while the persistent storage already exists (currently, the directory /var/lib/mariadb of the host is used), a different approach should be used after the image build process.
 125
 126 To this end, another script has been developed, namely validation/docker/mariadb/deploy_with_existing_storage.sh which easily deploys the container. This script accepts the following as input parameters:
 127
 128 CONTAINER_NAME, the name of the container, default value is akraino-validation-mariadb
 129 MARIADB_ROOT_PASSWORD, the desired mariadb root user password, this variable is required
 130 REGISTRY, the registry of the mariadb image, default value is akraino
 131 NAME, the name of the mariadb image, default value is validation
 132 TAG_PRE, the first part of the image version, default value is mariadb
 133 TAG_VER, the last part of the image version, default value is latest
 134 MARIADB_HOST_PORT, the port on which mariadb is exposed on host, default value is 3307
 135
 136 In order to deploy the image using only the required parameters and the existing persistent storage, the below instructions should be followed:
 137
 138 The mariadb root user password (currently the UI connects to the database using root privileges) should be configured using the appropriate variable and the following commands should be executed:
 139
 140 .. code-block:: console
 141
 142     cd validation/docker/mariadb
 143     ./deploy_with_existing_persistent_storage.sh TAG_PRE=dev-mariadb MARIADB_ROOT_PASSWORD=<root user password>
 144
 145 Finally, if the database must be re-deployed (it is assumed that the corresponding mariadb container has been stopped and deleted) and the old persistent storage must be deleted, the directory on the host machine where data is stored should be first deleted (note that all database's data will be lost).
 146
 147 To this end, after the image build process, the following commands should be executed:
 148
 149 .. code-block:: console
 150
 151     sudo rm -rf /var/lib/mariadb
 152     cd validation/docker/mariadb
 153     ./deploy.sh TAG_PRE=dev-mariadb MARIADB_ROOT_PASSWORD=<root user password> UI_ADMIN_PASSWORD=<UI admin user password> UI_AKRAINO_PASSWORD=<UI akraino user password>
 154     mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ../../ui/db-scripts/examples/initialize_db_example.sql
 155
 156 In the context of the full control loop mode, the following tables must be initialized with appropriate data:
 157
 158 - lab (here every lab owner should store the name of the lab)
 159 - timeslot (here every lab owner should register the available timeslots that can be used for blueprint validation test execution)
 160 - silo (here every lab owner should register the silo which is used for storing results in Nexus, for example for AT&T lab the value is 'att-blu-val')
 161 - blueprint (here every blueprint owner should register the name of the blueprint)
 162 - blueprint_instance_for_validation (here every blueprint owner should register the blueprint instances for validation, i.e. version, layer and description of a layer)
 163
 164 The following file can be used for initializing the aforementioned data (as it was performed in the above example using the 'mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ../../ui/db-scripts/examples/initialize_db_example.sql' command):
 165
 166     db-scripts/examples/initialize_db_example.sql
 167
 168 Some of this data is illustrated below (refer to 'org.akraino.validation.ui.data' package for more info regarding available values):
 169
 170 .. code-block:: console
 171
 172     Lab
 173     id:1, lab:0 (0 stands for AT&T)
 174
 175     Timeslots:
 176     id:1 , start date and time: 'now', duration: null, lab: 1
 177
 178     Silo
 179     id:1, silo: 'att-blu-val', lab: 1
 180
 181     Blueprints:
 182     id: 3 , name : 'REC'
 183
 184     Blueprint Instances:
 185     id: 2, blueprint_id: 3 (i.e. REC), version: "latest", layer: 0 (i.e. Hardware), layer_description: "AT&T Hardware"
 186
 187 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.
 188
 189 Based on this data, the UI enables the user to select an appropriate blueprint instance for validation.
 190
 191 Currently, this data cannot be retrieved dynamically by the UI (see limitations subsection). For this reason, in cases of new data, a user should define new entries in this database.
 192
 193 For example, if a user wants to define a new lab with the following data:
 194
 195     lab: Community
 196
 197 the following file should be created:
 198
 199 name: dbscript
 200 content:
 201     SET FOREIGN_KEY_CHECKS=1;
 202     use akraino;
 203     insert into lab values(2, 2);
 204
 205 2 stands for community lab. Refer to 'org.akraino.validation.ui.data' package for more info.
 206
 207 Then, the following command should be executed:
 208
 209 .. code-block:: console
 210
 211     mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ./dbscript.sql
 212
 213 For example, if a user wants to define a new timeslot with the following data:
 214
 215     start date and time:'now', duration: 0, lab: AT&T
 216
 217 the following file should be created:
 218
 219 name: dbscript
 220 content:
 221     SET FOREIGN_KEY_CHECKS=1;
 222     use akraino;
 223     insert into timeslot values(2, 'now', null, 1);
 224
 225 1 is the id of the AT&T lab.
 226
 227 Then, the following command should be executed:
 228
 229 .. code-block:: console
 230
 231     mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ./dbscript.sql
 232
 233 For example, if a user wants to define a new silo with the following data:
 234
 235     silo: 'community-blu-val', lab: AT&T
 236
 237 the following file should be created:
 238
 239 name: dbscript
 240 content:
 241     SET FOREIGN_KEY_CHECKS=1;
 242     use akraino;
 243     insert into silo values(2, 'community-blu-val', 2);
 244
 245 2 is the id of the community lab.
 246
 247 Then, the following command should be executed:
 248
 249 .. code-block:: console
 250
 251     mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ./dbscript.sql
 252
 253 Furthermore, if a user wants to define a new blueprint, namely "newBlueprint" and a new instance of this blueprint with the following data:
 254
 255     version: "latest", layer: 2 (i.e. K8s), layer_description: "K8s with High Availability Ingress controller"
 256
 257 the following file should be created:
 258
 259 name: dbscript
 260 content:
 261     SET FOREIGN_KEY_CHECKS=1;
 262     use akraino;
 263     insert into blueprint (blueprint_id, blueprint_name) values(4, 'newBlueprint');
 264     insert into blueprint_instance (blueprint_instance_id, blueprint_id, version, layer, layer_description) values(6, 4, 'latest', 2, 'K8s with High Availability Ingress controller');
 265
 266 Then, the following command should be executed:
 267
 268 .. code-block:: console
 269
 270     mysql -p<MARIADB_ROOT_PASSWORD> -uroot -h <IP of the mariadb container> < ./dbscript.sql
 271
 272 The UI will automatically retrieve this new data and display it to the user.
 273
 274 - Jenkins Configuration
 275
 276 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.
 277
 278 It should be noted that it is not the UI responsibility to deploy a Jenkins instance.
 279
 280 Furthermore, this instance must have the following option enabled: "Manage Jenkins -> Configure Global Security -> Prevent Cross Site Request Forgery exploits".
 281
 282 Also, currently, the corresponding Jenkins job should accept the following as input parameters: "SUBMISSION_ID", "BLUEPRINT", "VERSION", "LAYER" and "UI_IP".
 283 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.
 284 The "BLUEPRINT", "VERSION" and "LAYER" parameters are configured by the UI user.
 285
 286 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)
 287
 288 .. code-block:: console
 289
 290     cookie=`curl -v -H "Content-Type: application/x-www-form-urlencoded" -X POST --insecure --silent http://$UI_IP:8080/AECBlueprintValidationUI/login_external -d "loginId=akraino&password=akraino" 2>&1 | grep "Set-Cookie: " | awk -F ':' '{print $2}'`
 291     curl -v --cookie $cookie -H "Content-Type: application/json" -X POST --insecure --silent http://$UI_IP:8080/AECBlueprintValidationUI/api/jenkinsJobNotification/ --data '{"submissionId": "'"$SUBMISSION_ID"'" , "name":"'"$JOB_NAME"'", "buildNumber":"'"$BUILD_NUMBER"'"}'
 292
 293 It should be noted that the credentials user=akraino and password=akraino defined in the above commands should be replaced with the credentials of a real UI user. Recall that these credentials are defined in the database.
 294
 295 - Nexus server
 296
 297 All the blueprint validation results are stored in Nexus server for both modes of the UI.
 298
 299 It should be noted that it is not the UI responsibility to deploy a Nexus server.
 300
 301 In the context of the full control loop, these results must be available in the following url:
 302
 303     https://nexus.akraino.org/content/sites/logs/<lab_silo>/job/<Jenkins Job name>/<Jenkins job number>/results/<layer>/<name_of_the_test_suite>.
 304
 305 where <lab_silo> is the silo used by a lab for storing results in Nexus (for example 'att-blu-val'), <Jenkins job name> is the Jenkins job name that is triggered by the UI, <Jenkins job number> is the number of the Jenkins job that produced this result, <layer> is the blueprint layer and <name_of_the_test_suite> is the name of the corresponding test suite.
 306
 307 If multiple test suites are available, multiple test suite names should be created.
 308
 309 Moreover, the results should be stored in the 'output.xml' file and placed in the aforementioned URL using the following format:
 310
 311 TBD
 312
 313 In the context of partial control, the results must be available in the following url:
 314
 315 TBD
 316
 317 Compiling
 318 ~~~~~~~~~
 319
 320 .. code-block:: console
 321
 322     cd validation/ui
 323     mvn clean package
 324
 325 Deploying
 326 ~~~~~~~~~
 327
 328 The pom.xml file supports the building of an appropriate container image using the produced war file. Also, a script has been developed, namely validation/docker/ui/deploy.sh which easily deploys the container.
 329
 330 This script accepts the following as input parameters:
 331
 332 CONTAINER_NAME, the name of the contaner, default value is akraino-validation-ui
 333 DB_CONNECTION_URL, the URL connection with the akraino database of the maridb instance, this variable is required
 334 MARIADB_ROOT_PASSWORD, the mariadb root user password, this variable is required
 335 REGISTRY, the registry of the mariadb image, default value is akraino
 336 NAME, the name of the mariadb image, default value is validation
 337 TAG_PRE, the first part of the image version, default value is ui
 338 TAG_VER, the last part of the image version, default value is latest
 339 JENKINS_URL, the URL of the Jenkins instance, this variable is required
 340 JENKINS_USERNAME, the Jenkins user name, this variable is required
 341 JENKINS_USER_PASSWORD, the Jenkins user password, this variable is required
 342 JENKINS_JOB_NAME, the name of Jenkins job capable of executing the blueprint validation tests, this variable is required
 343 NEXUS_PROXY, the needed proxy in order for the Nexus server to be reachable, default value is none
 344 JENKINS_PROXY, the needed proxy in order for the Jenkins server to be reachable, default value is none
 345
 346 In order to build the image using only the required parameters, the following data is needed:
 347
 348 - The mariadb root user password (look at the Database subsection)
 349 - The URL for connecting to the akraino database of the mariadb
 350 - The Jenkins url
 351 - The Jenkins username and password
 352 - The name of Jenkins Job
 353
 354 Then, the following commands can be executed in order to build and deploy the UI container:
 355
 356 .. code-block:: console
 357
 358     cd validation/ui
 359     mvn docker:build -Ddocker.filter=akraino/validation:dev-ui-latest
 360     cd ../docker/ui
 361     ./deploy.sh TAG_PRE=dev-ui DB_CONNECTION_URL=<Url in order to connect to akraino database of the mariadb> MARIADB_ROOT_PASSWORD=<mariadb root password> JENKINS_URL=<http://jenkinsIP:port> JENKINS_USERNAME=<Jenkins user> JENKINS_USER_PASSWORD=<Jenkins password> JENKINS_JOB_NAME=<Jenkins job name>
 362
 363 The content of the DB_CONNECTION_URL can be for example 172.17.0.3:3306/akraino (i.e. IP and port of the database container plus '/akraino').
 364
 365 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).
 366
 367 If no proxy exists, the proxy ip and port variables should not be defined.
 368
 369 The UI should be available in the following url:
 370
 371     http://localhost:8080/AECBlueprintValidationUI
 372
 373 Note that the deployment uses the network host mode, so the 8080 must be available on the host.
 374
 375 User's guide
 376 -----------------
 377 TBD
 378
 379 Limitations
 380 -----------
 381 - The partial loop mode is not currently supported.
 382 - The UI has been tested using Chrome and Firefox browsers.
 383 - 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.
 384 - Results data manipulation (filtering, graphical representation, indexing in time order, etc) is not supported.
 385 - Only the following labs are supported: AT&T, Ericsson, Community and Arm.
 386 - Only the following tabs are functional: 'Committed Submissions', 'Blueprint Validation Results -> Get by submission id'.
 387 - The UI configures only the "BLUEPRINT", "VERSION", "LAYER", "SUBMISSION_ID" and "UI_IP" input parameters of the Jenkins job.
 388 - The silos, labs, and the available blueprints and timeslots must be manually configured in the mariadb database.
 389 - Logout action is not currently supported.