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

odsQuickstgarterPipeline can be customized by passing configuration options like this:

odsQuickstgarterPipeline(
  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 podContainers is set.

imageStreamTag

Container image tag of an ImageStream in your OpenShift cluster to use for the Jenkins agent container. This value is not used when podContainers or image is set.

alwaysPullImage

Determine whether to always pull the container image before each build run. Defaults to true. This value is not used when podContainers is set.

resourceRequestMemory

How much memory the container requests - defaults to 1Gi. This value is not used when podContainers is set.

resourceLimitMemory

Maximum memory the container can use - defaults to 2Gi. This value is not used when podContainers is set.

resourceRequestCpu

How much CPU the container requests - defaults to 10mi. This value is not used when podContainers is set.

resourceLimitCpu

Maximum CPU the container can use - defaults to 300mi. This value is not used when podContainers is set.

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 Jenkinsfile.

targetDir

The target directory in which the component files are places. Defaults to out.

Pipeline Context

When you write custom stages inside the closure passed to odsQuickstgarterPipeline, 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 odsQuickstgarterPipeline, 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 153.

buildUrl

Value of BUILD_URL. The URL where the results of the build can be found (e.g. http://buildserver/jenkins/job/MyJobName/123/)

buildTime

Time of the build, collected when the odsQuickstgarterPipeline 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 Jenkinsfile.

targetDir

The target directory in which the component files are places. Defaults to out.

projectId

Project ID, e.g. foo.

componentId

Component ID, e.g. be-auth-service.

packageName

Package name, retrieved from PACKAGE_NAME build parameter.

group

Group, retrieved from GROUP build parameter.

odsNamespace

Central namespace where images are located, retrieved from ODS_NAMESPACE build parameter.

odsImageTag

Image tag used for the agent pod, retrieved from ODS_IMAGE_TAG build parameter.

odsGitRef

Git ref, retrieved from ODS_GIT_REF build parameter.

bitbucketUrl

Bitbucket URL - value taken from BITBUCKET_URL. If BITBUCKET_URL is not present, it will default to https://<BITBUCKET_HOST>`. bitbucketHost is an alias for bitbucketUrl.

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:

odsQuickstgarterPipeline(
  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 ${context.sourceDir}/openshift.

envFile

Parameter file to use, defaults to ${context.sourceDir}/ocp.env

selector

Label selector to constrain tailor apply to, defaults to app=${context.projectId}-${context.componentId}.

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

Available options:

Option Description

source

Jenkinsfile template to use, defaults to Jenkinsfile.template

target

Jenkinsfile filename, defaults to Jenkinsfile

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

sonar-project.properties template to use, defaults to sonar-project.properties.template

target

sonar-project.properties filename, defaults to sonar-project.properties

odsQuickstarterStageForkODS

Forks a component from ODS

Available options:

Option Description

odsComponent

the component from (github) ODS to fork