This page introduces how the ONAP toolchain is setup and particularly how the Jenkins instance(s) is/are managed

In order to version control the Jenkins configuration, the configuration of all Jenkins jobs is managed though a tool called Jenkins Job Builder (JJB).

The below pages give an overview of how this tool is used in ONAP and how the current jobs are setup

Though the documentation is well written and provides all the needed information to understand how to write jobs, we wanted to give another approach on the Jenkins Job Builder usage. It's mainly lead by our discovery of the tool on our implementation case.

For most of our questions, the official documentation had the answer. Please consider reading it in case of trouble. If you think the information is interesting enough to share, we would be very pleased if you can make a contribution to this document.

For the sake of ease, you can find the official documentation here : http://docs.openstack.org/infra/jenkins-job-builder/

JJB, or Jenkins Job Builder, allows you to get your Jenkins job setup with simple human reable yaml files.
It allows you to have Jenkins configuration stored as code, versionnable, reusable, auditable.

As a picture is worth few lines, here are both in one:

Open

Using Jenkins Job Builder, we describe projects that contains jobs. Those jobs are mainly based on templates.
And to describe both, you have access to user defined macros and variables.

The projects will then be mapped to grouping tabs on Jenkins, and jobs to the actual jenkins jobs. Note that the project can describe things that will be common to each jobs.

For the sake of example, the following guide will use the MSO project to picture how to introduce the jobs needed.

The following file hierarchy of the repository (ci-management) is similar to the following :

jenkins-scripts jjb --- ci-management | --- ci-management-macros.yaml | --- ci-management.yaml | --- raw-include-packer-validate.sh --- global-defaults.yaml --- global-macros.yaml --- global-templates-java.yaml --- global-templates-python.yaml --- include-raw-deploy-archives.sh --- mso | --- mso-libs.yaml | --- mso.yaml packer scripts

The main and most interesting part is the jjb folder where the whole Jenkins Job Builder configuration lies.

The folders contains project specific information while files at the main folder containers templates, macros and default global values like their names states.

For Mso projects, we wanted to separate the main Mso app and the libs that should be compiled, tested and deployed. For that purpose, we created 2 yaml files in the mso folder : one for the main mso app, mso.yaml, and on for the mso-lib repository which contains the modified openstack library, mso-libs.yaml. If we had more libs, we would have integrated those in the mso-lib file.

----project:name:mso-libsproject-name:'mso-libs'jobs:-'{project-name}-{stream}-verify-java'-'{project-name}-{stream}-merge-java'-'{project-name}-{stream}-release-java-daily'project:'mso/libs'stream:-'master':branch:'master'mvn-settings:'mso-settings'# due to a strange macro / variable translation problem this needs to be# passed as a string block to properly get the properties correctly defined# in the jobmaven-deploy-properties:|deployAtEnd=truefiles:'**'archive-artifacts:''

The most interesting part of this file is the jobs section. It lists all the jobs that should be created.

The 3 jobs are composed of the name of a template, which itself has 2 parameters : project-name and stream.

The values for those parameters are taken from the variable project-name and the stream list. This will result in 3 jobs in Jenkins. By adding another stream, then there would be 6 jobs deployed on Jenkins, 3 for the master stream, 3 for the added stream.

Another interesting part is the project section. Which corresponds to the gerrit project that is concerned by out jobs.

http://docs.openstack.org/infra/jenkins-job-builder/definition.html#project

job-template:name:'{project-name}-{stream}-verify-java'project-type:freestyleconcurrent:truenode:'{build-node}'properties:-ecomp-infra-properties:build-days-to-keep:'{build-days-to-keep}'parameters:-ecomp-infra-parameters:project:'{project}'branch:'{branch}'refspec:'refs/heads/{branch}'artifacts:'{archive-artifacts}'scm:-gerrit-trigger-scm:refspec:'$GERRIT_REFSPEC'choosing-strategy:'gerrit'wrappers:-ecomp-infra-wrappers:build-timeout:'{build-timeout}'triggers:-gerrit-trigger-patch-submitted:server:'{server-name}'project:'{project}'branch:'{branch}'files:'**'builders:-provide-maven-settings:global-settings-file:'global-settings'settings-file:'{mvn-settings}'-maven-target:maven-version:'mvn33'goals:'clean install'settings:'{mvn-settings}'settings-type:cfpglobal-settings:'global-settings'global-settings-type:cfp

The global templates can be found in the the global-templates-java.yaml file. Those are generic templates, that should meet most project needs.

Note: if your project needs more specific ones, you should be able to overwrite the template parameters in the projects. If it's not sufficient, please create your template in your project directory.

Current ones contain the following parts : - name - node - properties - parameters - scm - wrappers - triggers - builders

The name can contain parameters that will be expanded using the variables provided upstread (in the project). Example : name: '{project-name}-{stream}-verify-java'

If the project-name of the project using that template is 'mso' and its stream is 'master', then it will be expanded to 'mso-master-verify-java'

Note that the naming convention we would like to keep on to keep on the project is trigger related. Also, please append the language name so that it doesn't conflicts with other programming language projects.

The Jenkins minion that will be used to execute the job. See build-node variable in global-defaults for the default one. Other possibilities can be found at the end of this document.

This sections should be used to set properties from jenkins job properties.

http://docs.openstack.org/infra/jenkins-job-builder/properties.html

This section provides allows you to setup build parameters for the Jenkins job.

http://docs.openstack.org/infra/jenkins-job-builder/parameters.html

This section provides information about which repo should be fetched, and how. In the example case, the gerrit-trigger-scm is a macro that contains the gerrit definition to fetch a repo.

http://docs.openstack.org/infra/jenkins-job-builder/scm.html

Wrappers are intended to change the behaviour of the build. See the official documentation in case you might need them.

http://docs.openstack.org/infra/jenkins-job-builder/wrappers.html

As there's no manual execution of the jobs (except on special request), the triggers describe how and when the build should be executed.

Most interesting ones are: