Sandbox_Setup.md

   1 ## ONAP Jenkins Sandbox Process:
   2
   3 ONAP Jenkins Sandbox provides you Jenkins Job testing/experimentation environment
   4 that can be used before pushing job templates to the production
   5 [Jenkins](https://jenkins.onap.org).
   6
   7 It is configured similar to the ONAP [ci-management] production instance;
   8 however, it cannot publish artifacts or vote in Gerrit. Be aware that this is a
   9 test environment, and as such there a limited allotment of minions to test on
  10 before pushing code to the ONAP repos.
  11 Keep the following points in mind prior to beginning work on ONAP Jenkins Sandbox
  12 environment:
  13
  14 - Jobs are automatically deleted every weekend
  15 - Committers can login and configure Jenkins jobs in the sandbox directly
  16 - Sandbox jobs CANNOT perform any upload tasks
  17 - Sandbox jobs CANNOT vote on Gerrit
  18 - Jenkins nodes are configured using ONAP openstack VMs and you can not access
  19   these VMs directly.
  20
  21 Before you proceed further, ensure you have a Linux Foundation ID (LFID), which is
  22 required to access Gerrit & Jenkins. Also, to get an access to Sandbox environment
  23 please send email to helpdesk@onap.org (LF helpdesk team)
  24
  25 To download **ci-management**, execute the following command to clone the
  26 **ci-managment** repository.
  27
  28 `git clone ssh://<LFID>@gerrit.onap.org:29418/ci-management --recursive && scp -p -P 29418 \
  29 <LFID>@gerrit.onap.org:hooks/commit-msg ci-management/.git/hooks/`
  30
  31 Once you successfully clone the repository, next step is to install JJB
  32 (Jenkins Job Builder) in order to experiment with Jenkins jobs.
  33
  34 ### Execute the following commands to install JJB on your machine:
  35
  36 ```
  37 cd ci-management
  38 sudo apt-get install python-virtualenv
  39 virtualenv onap_sandbox
  40 source onap_sandbox/bin/activate
  41 pip install jenkins-job-builder
  42 jenkins-jobs --version
  43 jenkins-jobs test --recursive jjb/
  44 ```
  45
  46 ### Make a copy of the example JJB config file (in the builder/ directory)
  47
  48 Backup the jenkins.ini.example to jenkins.ini
  49
  50 `cp jenkins.ini.example jenkins.ini`
  51
  52 After copying the jenkins.ini.example, modify `jenkins.ini` with your
  53 **Jenkins LFID username**, **API token** and **ONAP jenkins sandbox URL**
  54
  55 ```
  56 [job_builder]
  57 ignore_cache=True
  58 keep_descriptions=False
  59 include_path=.:scripts:~/git/
  60 recursive=True
  61
  62 [jenkins]
  63 user=jwagantall <Provide your Jenkins Sandbox username>
  64 password= <Refer below steps to get API token>
  65 url=https://jenkins.onap.org/sandbox
  66 This is deprecated, use job_builder section instead
  67 ignore_cache=True
  68 ```
  69 ### How to retrieve API token?
  70 Login to the [Jenkins Sandbox](https://jenkins.onap.org/sandbox/), go to your user
  71 page by clicking on your username. Click **Configure** and then click **Show API Token**.
  72
  73 To work on existing jobs or create new jobs, navigate to the `/jjb` directory where you
  74 will find all job templates for the project.  Follow the below commands to test,
  75 update or delete jobs in your sandbox environment.
  76
  77 ## To Test a Job:
  78
  79 After you modify or create jobs in the above environment, it's good practice
  80 to test the job in sandbox environment before you submit this job to production CI environment.
  81
  82 `jenkins-jobs --conf jenkins.ini test jjb/ <job-name>`
  83
  84 **Example:** `jenkins-jobs --conf jenkins.ini test jjb/ sdc-master-verify-java`
  85
  86 If the job you’d like to test is a template with variables in its name, it must be
  87 manually expanded before use. For example, the commonly used template `sdc-{stream}-verify-java`
  88 might expand to `sdc-master-verify-java`.
  89
  90 A successful test will output the XML description of the Jenkins job described by the
  91 specified JJB job name.
  92
  93 Execute the following command to pipe-out to a directory:
  94
  95 `jenkins-jobs --conf jenkins.ini test jjb/ <job-name> -o <directoryname>`
  96
  97 The output directory will contain files with the XML configurations.
  98
  99 ## To Update a job:
 100
 101 Ensure you’ve configured your `jenkins.ini` and verified it by
 102 outputting valid XML descriptions of Jenkins jobs. Upon successful
 103 verification, execute the following command to update the job to the
 104 Jenkins sandbox.
 105
 106 `jenkins-jobs --conf jenkins.ini update jjb/ <job-name>`
 107
 108 **Example:** `jenkins-jobs --conf jenkins.ini update jjb/ sdc-master-verify-java`
 109
 110 ## Trigger jobs from Jenkins Sandbox:
 111
 112 Once you push the Jenkins job configuration to the ONAP Sandbox environment,
 113 run the job from Jenkins Sandbox webUI. Follow the below process to trigger the build:
 114
 115 Step 1: Login into the [Jenkins Sandbox WebUI](https://jenkins.onap.org/sandbox/)
 116
 117 Step 2: Click on the **job** which you want to trigger, then click
 118 **Build with Parameters**, and finally click **Build**.
 119
 120 Step 3: Verify the **Build Executor Status** bar and make sure that the build is triggered
 121 on the available executor. In Sandbox you may not see all platforms build executors and
 122 you don't find many like in production CI environment.
 123
 124 Once the job is triggered, click on the build number to view the job
 125 details and the console output.
 126
 127 ## To Delete a Job:
 128
 129 Execute the following command to Delete a job from Sandbox:
 130
 131 `jenkins-jobs --conf jenkins.ini delete jjb/ <job-name>`
 132
 133 **Example:** `jenkins-jobs --conf jenkins.ini delete jjb/ sdc-master-verify-java`
 134
 135 The above command would delete the `sdc-master-verify-java` job.
 136
 137 ## Modify an Existing Job:
 138
 139 In the ONAP Jenkins sandbox, you can directly edit or modify the job configuration
 140 by selecting the job name and clicking on the **Configure** button. Then, click the
 141 **Apply** and **Save** buttons to save the job.
 142
 143 However, it is recommended to simply modify the job in your terminal and then follow
 144 the previously described steps in **To Test a Job** and **To Update a Job** to perform
 145 your modifications.
 146
 147 ## More online documentation:
 148
 149 https://docs.openstack.org/infra/jenkins-job-builder/