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