docs/internship/testapi_evolution/index.rst

   1 =======
   2 License
   3 =======
   4
   5 Functest Docs are licensed under a Creative Commons Attribution 4.0
   6 International License.
   7 You should have received a copy of the license along with this.
   8 If not, see <http://creativecommons.org/licenses/by/4.0/>.
   9
  10 ==================
  11 Test API evolution
  12 ==================
  13
  14 Author: Sakala Venkata Krishna Rohit
  15 Mentors: S. Feng, J.Lausuch, M.Richomme
  16
  17 Abstract
  18 ========
  19
  20 The testapi is used by all the test opnfv projects to report results.
  21 It is also used to declare projects, test cases and labs. A major refactoring
  22 has been done in Colorado with the introduction of swagger. The testapi is defined in Functest
  23 developer guide. The purpose of this project is to add more features to the testapi that automate
  24 the tasks that are done manually now, though there are tasks other than automation.
  25
  26 Version history
  27 ===============
  28
  29 +------------+----------+------------------+------------------------+
  30 | **Date**   | **Ver.** | **Author**       | **Comment**            |
  31 |            |          |                  |                        |
  32 +------------+----------+------------------+------------------------+
  33 | 2016-11-14 | 0.0.1    | Morgan Richomme  | Beginning of the       |
  34 |            |          | (Orange)         | Internship             |
  35 +------------+----------+------------------+------------------------+
  36 | 2017-02-17 | 0.0.2    | S.V.K Rohit      | End of the Internship  |
  37 |            |          | (IIIT Hyderabad) |                        |
  38 +------------+----------+------------------+------------------------+
  39
  40 Overview:
  41 =========
  42
  43 The internhip time period was from Nov 14th to Feb 17th. The project prosposal page is here `[1]`_.
  44 The intern project was assigned to Svk Rohit and was mentored by S. Feng, J.Lausuch, M.Richomme.
  45 The link to the patches submitted is `[2]`_. The internship was successfully completed and the
  46 documentation is as follows.
  47
  48 Problem Statement:
  49 ------------------
  50
  51 The problem statement could be divided into pending features that needed to be added into testapi
  52 repo. The following were to be accomplished within the internship time frame.
  53
  54 * **Add verification jenkins job for the testapi code**
  55     The purpose of this job is to verify whehter the unit tests are successful or not with the
  56     inclusion of the patchset submitted.
  57
  58 * **Automatic update of opnfv/testapi docker image**
  59     The docker image of testapi is hosted in the opnfv docker hub. To ensure that the testapi image
  60     is always updated with the repository, automatic updation of the image is necessary and a job
  61     is triggered whenever a new patch gets merged.
  62
  63 * **Automation deployment of testresults.opnfv.org/test/ website**
  64     In the same manner as the docker image of testapi is updated, the testapi website needs to be
  65     in sync with the repository code. So, a job has been added to the opnfv jenkins ci for the
  66     updation of the testresults website.
  67
  68 * **Generate static documentation of testapi calls**
  69     The purpose of this is to give an static/offline view of testapi. If someone wants to have a
  70     look at the Restful apis of testapi, he/she does't need to go to the website, he can download
  71     a html page and view it anytime.
  72
  73 * **Backup MongoDB of testapi**
  74     The mongoDB needs to be backed up every week. Till now it was done manually, but due to this
  75     internship, it is now automated using a jenkins job.
  76
  77 * **Add token based authorization to the testapi calls**
  78     The token based authorization was implemented to ensure that only ci_pods could access the
  79     database. Authentication has been added to only delete/put/post requests.
  80
  81 Curation Phase:
  82 ---------------
  83
  84 The curation phase was the first 3 to 4 weeks of the internship. This phase was to get familiar
  85 with the testapi code and functionality and propose the solutions/tools for the tasks mentioned
  86 above. Swagger codegen was choosen out of the four tools proposed `[3]`_ for generating static
  87 documentaion.
  88
  89 Also, specific amount of time was spent on the script flow of the jenkins jobs. The automatic
  90 deployment task involves accessing a remote server from inside the jenkins build. The deployment
  91 had to be done only after the docker image update is done. For these constraints to satisfy, a
  92 multijob jenkins job was choosen instead of a freestyle job.
  93
  94 Important Links:
  95 ----------------
  96
  97 * MongoDB Backup Link                 - `[4]`_
  98 * Static Documentation                - `[5]`_
  99 * TestAPI Token addition to ci_pods   - `[6]`_
 100
 101 Schedule:
 102 =========
 103
 104 The progress and completion of the tasks is described in the below table.
 105
 106 +--------------------------+------------------------------------------+
 107 | **Date**                 | **Comment**                              |
 108 |                          |                                          |
 109 +--------------------------+------------------------------------------+
 110 | Nov 14th - Dec 31st      | Understand Testapi code and the          |
 111 |                          | requirements.                            |
 112 +--------------------------+------------------------------------------+
 113 | Jan 1st  - Jan 7th       | Add jenkins job to create static         |
 114 |                          | documentation and write build scripts.   |
 115 +--------------------------+------------------------------------------+
 116 | Jan 8th  - Jan 21st      | Add verification jenkins job for unit    |
 117 |                          | tests.                                   |
 118 +--------------------------+------------------------------------------+
 119 | Jan 22nd - Jan 28th      | Add jenkins job for mongodb backup       |
 120 |                          |                                          |
 121 +--------------------------+------------------------------------------+
 122 | Jan 29th - Feb 11th      | Enable automatic deployment of           |
 123 |                          | testresults.opnfv.org/test/              |
 124 +--------------------------+------------------------------------------+
 125 | Feb 12th - Feb 17th      | Add token based authentication           |
 126 |                          |                                          |
 127 +--------------------------+------------------------------------------+
 128
 129 FAQ's
 130 =====
 131
 132 This section lists the problems that I have faced and the understanding that I have acquired during
 133 the internship. This section may help other developers in solving any errors casused because of the
 134 code written as a part of this internship.
 135
 136
 137 Test Api
 138 --------
 139
 140 What is the difference between defining data_file as "/etc/.." and "etc/.." in setup.cfg ?
 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 142
 143 If in the setup.cfg, it is defined as
 144
 145 [files]
 146 data_files =
 147 etc/a.conf = etc/a.conf.sample
 148
 149 then it ends up installed in the /usr/etc/. With this configuration, it would be installed
 150 correctly within a venv. but when it is defined as
 151
 152 [files]
 153 data_files =
 154 /etc/a.conf = etc/a.conf.sample
 155
 156 then it ends up installed on the root of the filesystem instead of properly be installed within the
 157 venv.
 158
 159 Which attribute does swagger-codegen uses as the title in the generation of document generation ?
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 162 It uses the nickname of the api call in swagger as the title in the generation of the document
 163 generation.
 164
 165 Does swagger-codegen take more than one yaml file as input ?
 166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 167
 168 No, swagger-codegen only takes one yaml file as input to its jar file. If there more than one yaml
 169 file, one needs to merge them and give it as an input keeping mind the swagger specs.
 170
 171
 172 Jenkins & JJB
 173 -------------
 174
 175 Which scm macro is used for verification jenkins jobs ?
 176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 177
 178 There are two macros for scm one is git-scm and other git-scm-gerrit. git-scm-gerrit is used for
 179 verification jenkins job.
 180
 181 Does the virtualenv created in one build script exists in other build scripts too ?
 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 183
 184 No, the virtualenv created in one build script only exists in that build script/shell.
 185
 186 What parameters are needed for the scm macros ?
 187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 188
 189 Project and Branch are the two parameters needed for scm macros.
 190
 191 What is the directory inside the jenkins build ?
 192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 193
 194 The directory of the jenkins build is the directory of the repo. `ls $WORKSPACE` command will give
 195 you all the contents of the directory.
 196
 197 How to include a bash script in jenkins job yaml file ?
 198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 199
 200 An example might be apt here as an answer.
 201
 202 builders:
 203     - shell:
 204         !include-raw: include-raw001-hello-world.sh
 205
 206
 207 How do you make a build server run on a specific machine ?
 208 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 209
 210 It can be done by defining a label parameter 'SLAVE_LABEL' or in OPNFV , there are macros for each
 211 server, one can use those parameter macros.
 212 Ex: opnfv-build-defaults. Note, if we use macro, then no need to define GIT_BASE, but if one uses
 213 SLAVE_LABEL, one needs to define a parameter GIT_BASE. This is because macro already has GIT_BASE
 214 defined.
 215
 216 What job style should be used when there is a situation like one build should trigger other builds
 217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 218 or when different build scripts need to be run on different machines ?
 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 220
 221 MultiJob style should be used as it has phases where each phase can be taken as a build scipt and
 222 can have its own parameters by which one can define the SLAVE_LABEL parameter.
 223
 224 References:
 225 ===========
 226
 227 _`[1]` : https://wiki.opnfv.org/display/DEV/Intern+Project%3A+testapi+evolution
 228
 229 _`[2]` : https://gerrit.opnfv.org/gerrit/#/q/status:merged+owner:%22Rohit+Sakala+%253Crohitsakala%2540gmail.com%253E%22
 230
 231 _`[3]` : https://docs.google.com/document/d/1jWwVZ1ZpKgKcOS_zSz2KzX1nwg4BXxzBxcwkesl7krw/edit?usp=sharing
 232
 233 _`[4]` : http://artifacts.opnfv.org/testapibackup.html
 234
 235 _`[5]` : http://artifacts.opnfv.org/releng/docs/testapi.html
 236
 237 _`[6]` : http://artifacts.opnfv.org/functest/review/26047/devguide/index.html#test-api-authorization