Quickstarter Pipeline
This pipeline allows to have a minimal Jenkinsfile
for a quickstarter by providing all language-agnostic provision aspects. The goal is to duplicate as little as possible between quickstarters.
This pipeline is NOT for building components. It is only to be used when you are authoring a (new) quickstarter itself. If you are building a component (an application), please refer to the component pipeline. |
Usage
Load the shared library in your Jenkinsfile
like this:
def odsNamespace = env.ODS_NAMESPACE ?: 'ods'
def odsGitRef = env.ODS_GIT_REF ?: 'master'
def odsImageTag = env.ODS_IMAGE_TAG ?: 'latest'
library("ods-jenkins-shared-library@${odsGitRef}")
odsQuickstarterPipeline(
imageStreamTag: "${odsNamespace}/jenkins-agent-golang:${odsImageTag}",
) { context ->
odsQuickstarterStageCopyFiles(context)
stage('Write go.mod') {
dir(context.targetDir) {
sh "go mod init module example.com/foo/bar"
}
}
odsQuickstarterStageCreateOpenShiftResources(context)
odsQuickstarterStageRenderJenkinsfile(context)
odsQuickstarterStageRenderSonarProperties(context)
}
There are many built-in stages like odsQuickstarterStageCopyFiles
that you can use, please see Stages for more details.
Pipeline Options
odsQuickstarterPipeline
can be customized by passing configuration options like this:
odsQuickstarterPipeline( imageStreamTag: 'ods/jenkins-agent-golang:3.x' )
Available options are:
Property | Description |
---|---|
image |
Container image to use for the Jenkins agent container. This value is not used when |
imageStreamTag |
Container image tag of an |
alwaysPullImage |
Determine whether to always pull the container image before each build run. Defaults to |
resourceRequestMemory |
How much memory the container requests - defaults to 1Gi. This value is not used when |
resourceLimitMemory |
Maximum memory the container can use - defaults to 2Gi. This value is not used when |
resourceRequestCpu |
How much CPU the container requests - defaults to 10m. This value is not used when |
resourceLimitCpu |
Maximum CPU the container can use - defaults to 300m. This value is not used when |
podLabel |
Pod label, set by default to a random label to avoid caching issues. Set to a stable label if you want to reuse pods across builds. |
podContainers |
Custom pod containers to use if the default, automatically configured container is not suitable for your use case (e.g. if you need multiple containers such as app and database). See Agent customization. |
podVolumes |
Volumes to make available to the pod. |
podServiceAccount |
Serviceaccount to use when running the pod. |
sourceDir |
The source directory of the quickstarter, relative to the root of the repository. Defaults to the directory containing the |
targetDir |
The target directory in which the component files are places. Defaults to |
Pipeline Context
When you write custom stages inside the closure passed to odsQuickstarterPipeline
, you have access to the context
, which is assembled for you on the master node. The context
can be influenced by changing the config map passed to odsQuickstarterPipeline
, see Pipeline Options.
The context
object contains the following properties:
Property | Description |
---|---|
jobName |
Value of JOB_NAME. It is the name of the project of the build. |
buildNumber |
Value of BUILD_NUMBER. The current build number, such as |
buildUrl |
Value of BUILD_URL. The URL where the results of the build can be found (e.g. |
buildTime |
Time of the build, collected when the odsQuickstarterPipeline starts. |
cdUserCredentialsId |
Credentials identifier (Credentials are created and named automatically by the OpenShift Jenkins plugin). |
sourceDir |
The source directory of the quickstarter, relative to the root of the repository. Defaults to the directory containing the |
targetDir |
The target directory in which the component files are places. Defaults to |
projectId |
Project ID, e.g. |
componentId |
Component ID, e.g. |
packageName |
Package name, retrieved from |
group |
Group, retrieved from |
odsNamespace |
Central namespace where images are located, retrieved from |
odsImageTag |
ODS image tag. Retrieved from |
odsGitRef |
ODS Git ref. Retrieved from |
agentImageTag |
Image tag used for the agent pod, retrieved from |
sharedLibraryRef |
Git reference used for the Jenkins shared library, retrieved from |
bitbucketUrl |
Bitbucket URL - value taken from |
gitUrlHttp |
URL of the Git repository to push to. |
Advanced
Agent customization
The agent used in the pipeline can be customized by adjusting the image
(or imageStreamTag
to
use. Further, alwaysPullImage
(defaulting to true
) can be used to
determine whether this image should be refreshed on each build.
Resource constraints of the container can be changed via resourceRequestCpu
,
resourceLimitCpu
, resourceRequestMemory
and resourceLimitMemory
.
The setting podVolumes
allows to mount persistent volume claims to the pod
(the value is passed to the podTemplate
call as volumes
).
To completely control the container(s) within the pod, set podContainers
(which is passed to the podTemplate
call as containers
).
Configuring of a customized agent container in a Jenkinsfile
:
odsQuickstarterPipeline( projectId: projectId, podContainers: [ containerTemplate( name: 'jnlp', // do not change, see https://github.com/jenkinsci/kubernetes-plugin#constraints image: "${env.DOCKER_REGISTRY}/foo-cd/jenkins-agent-custom", workingDir: '/tmp', resourceRequestCpu: '100m', resourceLimitCpu: '500m', resourceRequestMemory: '2Gi', resourceLimitMemory: '4Gi', alwaysPullImage: true, args: '' ) ], ... ) { context -> stageBuild(context) ... }
See the kubernetes-plugin documentation for possible configuration.
Stages
Each built-in stage (like odsQuickstarterStageCreateOpenShiftResources
) takes two arguments:
-
context
(required, this is the pipeline context) -
config
(optional, a map of configuration options)
Example:
odsQuickstarterStageCreateOpenShiftResources( context, [directory: 'common/foobar'] )
odsQuickstarterStageCopyFiles
Copies files from ${context.sourceDir}/files
to ${context.targetDir}
.
There are no configuration options.
odsQuickstarterStageCreateOpenShiftResources
Uses a set of OpenShift templates to create resources in OpenShift. The resources are created both in -dev
and -test
namespace. Tailor is used to apply the templates, and fed with a parameter file if it exists.
Available options:
Option | Description |
---|---|
directory |
Directory in which templates are located, defaults to |
envFile |
Parameter file to use, defaults to |
selector |
Label selector to constrain |
All the created OpenShift resources are automatically labeled to ease their management.
The quickstarter pipeline does a best effort to assign appropriate labels for a new component, based on the information of the quickstarter. This information can be customised by updating the component metadata.
Detailed information about the labelling can be found here.
odsQuickstarterStageRenderJenkinsfile
Processes a Jenkinsfile
template in the source directory by replacing tokens (@token@
) with actual values, and placing the rendered file into the target directory.
The handled replacements are:
-
@project_id@
⇒context.projectId
-
@component_id@
⇒context.componentId
-
@component_type@
⇒context.sourceDir
-
@git_url_http@
⇒context.gitUrlHttp
-
@ods_image_tag@
⇒context.odsImageTag
-
@ods_git_ref@
⇒context.odsGitRef
-
@agent_image_tag@
⇒context.agentImageTag
-
@shared_library_ref@
⇒context.sharedLibraryRef
Available options:
Option | Description |
---|---|
source |
|
target |
|
odsQuickstarterStageRenderSonarProperties
Processes a sonar-project.properties
template in the source directory by replacing tokens (@token@
) with actual values, and placing the rendered file into the target directory.
The handled replacements are:
-
@project_id@
⇒context.projectId
-
@component_id@
⇒context.componentId
Available options:
Option | Description |
---|---|
source |
|
target |
|