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 is 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 extend your permissions for uploading
  23 Jenkins configurations to Sandbox environment, you must raise a ticket to
  24 [Linux Foundation Help Center](https://support.linuxfoundation.org)
  25
  26 To download **ci-management**, execute the following command to clone the
  27 **ci-management** repository.
  28
  29 `git clone https://gerrit.onap.org/r/ci-management && (cd ci-management && curl -Lo \
  30 $(git rev-parse --git-dir)/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg; \
  31 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg)`
  32
  33 Make sure to sync global-jjb submodule using:
  34
  35 `git submodule update --init`
  36
  37 Once you successfully clone the repository, next step is to install JJB
  38 (Jenkins Job Builder) in order to experiment with Jenkins jobs.
  39
  40 ### Execute the following commands to install JJB on your machine:
  41
  42 ```
  43 cd ci-management
  44 pip install virtualenv
  45 virtualenv onap_sandbox
  46 source onap_sandbox/bin/activate
  47 pip install jenkins-job-builder
  48 jenkins-jobs --version
  49 jenkins-jobs test --recursive jjb/
  50 ```
  51
  52 ### Make a copy of the example JJB config file (in the ci-management/ directory)
  53
  54 Backup the jenkins.ini.example to jenkins.ini
  55
  56 `mkdir -p ~/.config/jenkins_jobs`
  57 `cp jenkins.ini.example ~/.config/jenkins_jobs/jenkins_jobs.ini`
  58
  59 After copying the jenkins.ini.example, modify `jenkins.ini` with your
  60 **Jenkins LFID username** and **API token**
  61
  62 ```
  63 [job_builder]
  64 ignore_cache=True
  65 keep_descriptions=False
  66 include_path=.
  67 recursive=True
  68 retain_anchors=True
  69
  70 [jenkins]
  71 user=jwagantall <Provide your Jenkins Sandbox username>
  72 password= <Refer below steps to get API token>
  73 url=https://jenkins.onap.org/sandbox
  74 query_plugins_info=False
  75 ```
  76 ### How to retrieve username and API token?
  77 Login to the [Jenkins Sandbox](https://jenkins.onap.org/sandbox/), go to your user
  78 page by clicking on your username - `Jenkins User ID` on this page is your Jenkins
  79 Sandbox username. Click **Configure** and then click **Add new Token**.
  80 After that specify a token name (optional) and click on **Generate** to generate and show
  81 new token. Please note down your token and store it securely.
  82
  83 To work on existing jobs or create new jobs, navigate to the `ci-management/jjb/` directory where you
  84 will find all job templates for the project.  Follow the below commands to test,
  85 update or delete jobs in your sandbox environment.
  86
  87 ## To Test a Job:
  88
  89 After you modify or create jobs in the above environment, it's good practice
  90 to test the job in sandbox environment before you submit this job to production CI environment.
  91
  92 `jenkins-jobs test jjb/ <job-name>`
  93
  94 **Example:** `jenkins-jobs test jjb/ sdc-master-verify-java`
  95
  96 If the job you’d like to test is a template with variables in its name, it must be
  97 manually expanded before use. For example, the commonly used template `sdc-{stream}-verify-java`
  98 might expand to `sdc-master-verify-java`.
  99
 100 A successful test will output the XML description of the Jenkins job described by the
 101 specified JJB job name.
 102
 103 Execute the following command to pipe-out to a directory:
 104
 105 `jenkins-jobs test jjb/ <job-name> -o <directoryname>`
 106
 107 The output directory will contain files with the XML configurations.
 108
 109 ## To Update a job:
 110
 111 Ensure you’ve configured your `jenkins_jobs.ini` and verified the changes by
 112 outputting valid XML descriptions of the relevant Jenkins jobs. Upon successful
 113 verification, execute the following command to update the job to the Jenkins sandbox.
 114
 115 `jenkins-jobs update jjb/ <job-name>`
 116
 117 **Example:** `jenkins-jobs update jjb/ sdc-master-verify-java`
 118
 119 ## Trigger jobs from Jenkins Sandbox:
 120
 121 Once you push the Jenkins job configuration to the ONAP Sandbox environment,
 122 run the job from Jenkins Sandbox webUI. Follow the below process to trigger the build:
 123
 124 Step 1: Login into the [Jenkins Sandbox WebUI](https://jenkins.onap.org/sandbox/)
 125
 126 Step 2: Click on the **job** which you want to trigger, then click
 127 **Build with Parameters**, and finally click **Build**.
 128
 129 Step 3: Verify the **Build Executor Status** bar and make sure that the build is triggered
 130 on the available executor. In Sandbox you may not see all platforms build executors and
 131 you don't find many like in production CI environment.
 132
 133 Once the job is triggered, click on the build number to view the job
 134 details and the console output.
 135
 136 ## To Delete a Job:
 137
 138 Execute the following command to Delete a job from Sandbox:
 139
 140 `jenkins-jobs delete jjb/ <job-name>`
 141
 142 **Example:** `jenkins-jobs delete jjb/ sdc-master-verify-java`
 143
 144 The above command would delete the `sdc-master-verify-java` job.
 145
 146 ## Modify an Existing Job:
 147
 148 In the ONAP Jenkins sandbox, you can directly edit or modify the job configuration
 149 by selecting the job name and clicking on the **Configure** button. Then, click the
 150 **Apply** and **Save** buttons to save the job.
 151
 152 However, it is recommended to simply modify the job in your terminal and then follow
 153 the previously described steps in **To Test a Job** and **To Update a Job** to perform
 154 your modifications.
 155
 156 ## More online documentation:
 157
 158 https://docs.openstack.org/infra/jenkins-job-builder/