lf-releng-docs
master
Facts to keep in mind before working on the 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 LF Helpdesk ticket (for the related project) 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 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.
This is the easiest and fastest way to start using the Sandbox. This is the recommended default way to use the Sandbox since this does not require the user to install JJB or configure it at all.
This is the recommended way to push jobs to the Sandbox system and does not require installation of Jenkins Job Builder locally.
To push jobs to the Sandbox with jjb-deploy, add a comment on the Gerrit patch from ci-management:
jjb-deploy <job name>
The resultant job’s configuration reflects the same code the patch’s code base in the Gerrit. The job pushed into the Sandbox will reflect the changes made in the patch.
Note
You can use * wildcard for job names. This is not a good practice. We highly recommended to use specific Jenkins job names instead.
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?
ConfigureShow API TokenTo 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.
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.
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 jjb/ <job-name>
For Example:
jenkins-jobs update jjb/ ci-management-jjb-merge
Execute the following command to Delete a job from Sandbox:
jenkins-jobs delete jjb/ <job-name>
For Example:
jenkins-jobs delete jjb/ ci-management-jjb-merge
You can also delete the job from the UI options in Jenkins Sandbox.
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
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:
You can click on the build number to view the job details and console output.