Jenkins Sandbox Guide¶
Sandbox Overview¶
Facts to keep in mind before working on the Sandbox:
Jobs are automatically deleted every Saturday at 08:00 UTC
Committers can login and configure Jenkins jobs in the Sandbox directly
Sandbox jobs cannot perform any upload/deploy tasks
Project configuration files and credentials are not loaded into the system
Sandbox jobs cannot vote on Gerrit
Jenkins nodes have the same OpenStack configuration as the production instance with minor differences.
Get access to the Jenkins Sandbox¶
The Sandbox provides a testing/experimentation environment used before pushing job templates to the production instance.
To access the Sandbox use: jenkins.example.org/sandbox
The access to the Sandbox uses the same LFID used in the production Jenkins instance, but in this case a new Helpdesk ticket needs creation to request the sandbox access.
The LF helpdesk team can add users to the appropriate group to grant permissions
to access the Sandbox via https://identity.linuxfoundation.org/.
The group that controls this access is <project>-jenkins-sandbox-access
For example:
https://identity.linuxfoundation.org/content/<project>-jenkins-sandbox-access
The requester will receive an invitation to join this group. Once accepted, the user can now access the Sandbox same way as the production Jenkins.
Push jobs to Jenkins Sandbox¶
Push jobs to the Jenkins Sandbox using one of these methods:
Method 1 is easier as it does not require installing anything on your local system. This method requires pushing the patch to Gerrit on each test. We recommend this method for quick one off edits or if you are testing another contributor’s patch.
Method 2 is more convenient for those who work on JJB templates more than once or twice.
Push jobs via Gerrit comment¶
This is the easiest and fastest way to start using the Jenkins Sandbox. This is the recommended way to use the Sandbox since this does not require a local installation of JJB.
To push jobs to the Jenkins Sandbox with the jjb-deploy job, add a comment on any Gerrit patch.
jjb-deploy <job name>
jjb-deploy ci-management-jjb-verify # Push the ciman JJB verify job.
Leaving a comment on a non-ci-management patch, the resultant job will use latest master branch of the ci-management repo.
Leaving a comment on a ci-management patch, the resultant job’s configuration will reflect patch’s code base in Gerrit.
Push jobs via JJB CLI¶
JJB CLI needs configuration first.
Note
Use this configuration if you prefer to use the JJB tool locally on your system.
Configure the file ~/.config/jenkins_jobs/jenkins_jobs.ini
as follows:
[job_builder]
ignore_cache=True
keep_descriptions=False
recursive=True
retain_anchors=True
update=jobs
[jenkins]
user=<Provide your Jenkins Sandbox user-id (LFID)>
password= <Refer below steps to get API token>
url=https://jenkins.example.org/sandbox
Note
The [jenkins] section is the default configuration section that JJB will
refer to when calling jenkins-jobs
without passing the -s | --server
option. If you work on more than one Jenkins system then configure sections
like [odl], [opnfv], [onap], etc… and pass jenkins-jobs -s odl
to make
it convenient to switch projects.
How to retrieve API token?
Login to the Jenkins Sandbox using your LFID
Go to the user page by clicking on your username on the top right
Click
Configure
Click
Show API Token
To start using the Sandbox, we must do a clone of ci-management or releng/builder (in case of ODL) repo for the project. For example:
git clone ssh://<LFID>@gerrit.example.org:29418/ci-management
Make sure you sync global-jjb also using:
git submodule update --init
Install JJB (Jenkins Job Builder).
Execute the following commands to install JJB on your machine:
cd ci-management (or cd builder)
pip install --user virtualenvwrapper
mkvirtualenv jjb
pip install jenkins-job-builder
jenkins-jobs --version
jenkins-jobs test --recursive jjb/
Note
More information on Python Virtual Environments
To work on existing jobs or create new jobs, navigate to the /jjb directory where you will find all job templates for the project. Follow the below commands to test, push or delete jobs in your Sandbox environment.
Verify JJB¶
After you edit or create new job templates, test the job in the Sandbox environment before you submit this job to production CI environment.
jenkins-jobs test jjb/ <job-name>
For Example:
jenkins-jobs test jjb/ ci-management-jjb-merge
If the job you would like to test is a template with variables in its name, it must be manually expanded before use. For example, the commonly used template {project-name}-jjb-merge might expand to ci-management-jjb-merge.
A successful test will output the XML description of the Jenkins job described by the specified JJB job name.
Execute the following command to pipe-out to a directory:
jenkins-jobs --conf jenkins.ini test jjb/ <job-name> -o target
The output directory will contain files with the XML configurations.
Push a Job¶
Ensure you have configured your jenkins.ini and verified it by outputting valid XML descriptions of Jenkins jobs. Upon successful verification, execute the following command to push the job to the Sandbox:
jenkins-jobs update -j jjb/ <job-name>
For Example:
jenkins-jobs update -j jjb/ ci-management-jjb-merge
Delete a Job¶
Execute the following command to Delete a job from Sandbox:
jenkins-jobs delete -j jjb/ <job-name>
For Example:
jenkins-jobs delete -j jjb/ ci-management-jjb-merge
You can also delete the job from the UI options in Jenkins Sandbox.
Edit Job via Web UI¶
In the Sandbox, you can directly edit the job configuration by selecting the job name and clicking on the Configure button. Click the Apply or Save (to save and exit the configuration) buttons to save the job.
This is useful in the case where you might want to test quick tweaks to a job before modifying the YAML.
Edit the job in your terminal and follow the described steps in Verify JJB and Push Job <push-job> to push any changes and have them ready to push to Gerrit.
Important
When pushing to the Sandbox with jenkins-jobs, do not forget the <job-name> parameter. Otherwise, JJB will push all job templates into the Sandbox and will flood the system.
If that happens, use `ctrl+c` to cancel the upload.
A successful run of the desired job will look like this:
INFO:jenkins_jobs.builder:Number of jobs generated: 1
Execute jobs in the Sandbox¶
Once you push the Jenkins job configuration to the Sandbox environment, run the job from the Sandbox WebUI. Follow the below process to trigger the build:
Login into the Jenkins Sandbox WebUI
Click on the job which you want to trigger
Click “Build with parameters”
Click Build
Verify the Build Executor Status bar to check on progress.
You can click on the build number to view the job details and console output.