Tools4Jenkins

Presentation

Tools4Jenkins is a Jenkins library which allows you to setup a jenkins infrastructure as code. This library is intertwined with Tools4Dev for configuration loading and job execution.

Jenkins configuration

Before configuring nodes and jobs, you have to create some base configuration in jenkins.

• Create credentials with slave_default_user as ID. This will be used for slave SSH connection.

• Create credentials with jenkins_git_credentials as ID. This will be used to connect to Git repositories.

• Create a _base_ node with the following configuration :

Name : _base_
Remote root directory : HOME
Launch method : Launch agents via SSH
Host : IP_ADDRESS
Credentials : slave_default_user

• Create a _Base_ folder at jenkins' root

• Inside _Base_ folder, create a _MultiBranchPipeline_ multibranch pipeline with the following configuration :

Branch Sources : Git :
    Project Repository : GIT_SOURCE
    Credentials : jenkins_git_credentials
    Behaviors : Filter by name (with regular expression) : Regular expression : GIT_BRANCH_FILTER
    Property strategy : Suppress automatic SCM triggerring
Build Configuration :
    Mode : by Jenkinsfile
    Script Path	: JENKINSFILE
Properties : Pipeline Libraries : Library :
    Name : main
    Branch : main
    Retrieval method : Modern SCM
    Source Code Management : Git :
        Project Repository : LIB_SOURCE
        Credentials : jenkins_git_credentials
        Behaviors : Discover branches

This is the base config needed to automaticaly create the configuration you will define during the next step.

XML configuration

The file ci-example.xml contains the configuration of your nodes, projects and jobs to generate. By editing this file, you will create your infrastructure at wks sync command invoke. This allows you to recreate very rapidly your CI in the event of a catastrophic failure. This uses the jenkins config you created at the previous step to generate jenkins config for your infrastructure.

configuration name="jenkins-lib" : add the git path to the Tools4Jenkins lib (unique)

configuration name="jenkins-root" : you might want to edit this if your jenkins path has been customised (unique)

node : add a node/agent (can be used multiple times) with a specific home and ip address (nodes will be linked to src/slaves/{XXX}.groovy more on that later)

repoGit : add a git repo for jobs (multiple) this will concat base, key and name to create the repo url

folder name="Home" : default job base folder, edit root= if your jenkins path has been customised (unique)

folder : add a folder to organize your projects (multiple) use folderBase= to place it in the tree

<pipeline uuid="Pipeline-Default" name="Pipeline-Default" folderBase="Base" jenkinsfile="jenkinsfile" repoGit="Test" branchFilter=".*"> : add a pipeline to build your project (multiple) repoGit= requires the name= part of a repoGit specified earlier

Slaves groovy config

You will need to create slaves file in src/slaves.

If you're only using a single agent you can edit src/slaves/main.groovy with details from your agent's env.

If you have multiple agents, you should add new groovy files with each agent's env informations.

• _Fedora_.groovy template for Linux based agents
• _OSX_.groovy template for MacOS based agents

Configuration details :

getName() : must return a string corresponding to <node> name from ci-example.xml
HOME : path to your agent's user home folder (not agent directory)
Tools4Dev_PATH : path to Tools4Dev installation
WS_ROOT : path to agent workdir (where it will execute jobs)
WORKSPACE : leave as defined, will get autogenerated at build time by system.jenkins.main.getWorkspace()

Apply config to Jenkins

As root with this project loaded in a console, use command wks sync. This will create projects folders, job folders and agent nodes with correct file permissions.

If you need to recreate a job, delete the corresponding directory in JENKINS_ROOT/jobs and execute wks sync command.

New job configuration example

You can refer yourself to this Tools4Jenkins PR to get a full example of all files to add/edit for a new project.