raaftech/jenkins repository overview

⁠Jenkins with Docker and OpenShift for Mule

This is a Jenkins container (Dockerfile) which you can use to run Mulesoft builds. It's been particularly tailored for running on OpenShift, but standalone works fine too.

In the sections below, you'll find out how to build and run this project's Docker image standalone and how to use the included OpenShift template files to deploy. tested on OpenShift 3.11.

⁠Table of Contents

• Pre-Requisites⁠
• Building Docker Images⁠
• Deployment on OpenShift⁠
• Environment Variables and Arguments⁠

⁠Pre-requisites

You need a reasonably recent version of Docker to build and run the Docker image. To run locally, in standalone mode, without the need to actually serve a large number of pipelines, you should be able to get away with about 2G of memory and a core or two for computation.

To run on OpenShift, you need an OpenShift cluster. I tested with version 3.11.

A small note about memory settings: This setup assumes a JVM of version 1.8.0 R191 or newer. The reason for that is that these versions of the JVM have the +EnableContainerSupport and +InitialRAMPercentage and +MaxRAMPercentage features, which we use to dynamically provide the dockerized JVM with the right amount of heap based on the memory assigned to the Pod via the OpenShift template YAML file. In other words, you don't need to tell the JVM explicitly how much memory to use, it does that automatically based on the max memory assigned to the pod.

Finally, I'm assuming a fairly recent modern OS environment where you have the docker and oc commands available via your PATH environment variable and know how to get by using either cmd.exe, powershell, ksh or bash.

⁠Building Docker images

Everything is essentially built around a weighty CentOS Linux image, on which we install the standard Jenkins stable RHEL RPM distribution.

The Dockerfile⁠ inherits from Red Hat's openshift/origin⁠ image.

Alright, without further ado, let's get that standalone Docker image up + running! First off, you should git clone this repository somewhere, start your command shell of choice and cd into the cloned repository's directory. Run the following:

• docker build -t someorg/jenkins:latest .
• docker run -d -p 8080:8080 -p 50000:50000 --rm --name jenkins someorg/jenkins:latest
• docker logs -f jenkins (<ctrl-c> when you've seen enough)
• curl http://localhost:8080 (the standard login screen)

And to clean up afterwards:

• docker stop jenkins
• docker container prune (optional, not needed when --rm was passed to docker run)
• docker volume prune (optional, cleans up the non-named volume entries)
• docker rmi someorg/jenkins:latest (removes the previously built image)
• docker rmi openshift/origin (removes the parent image)

If you completed the steps above, congratulations, you ran your first (I'm assuming) customized Jenkins image! This instance did not get configured with any of the options that the various environment variables make possible, as the default values of those variables essentially enable a standalone Jenkins master with all bells + whistles.

The changing of those environment variables and a few Docker specific settings is what makes it possible for a single Docker image for specific purposes and it's this that is key to running this setup in an OpenShift environment. For more info on that, read on!

⁠Deployment on OpenShift

in the templates⁠ subdirectory you'll find a selection of yaml files that set up various resources within an OpenShift environment. The statefulset should refer to the Docker image created above (i.e, wherever you pushed it, or the default, raaftech/jenkins). In this case, there are four types of resources:

• route: An HTTP endpoint that exposes the service for the outside world to consume;
• service: A port definition that defines which ports should be open amongst pods;
• statefulset: A set of pods that have identity and state associated with them;
• deployment: A set of pods that have no persistent identity and usually no state;

Essentially, the resources in an OpenShift environment represent the things you care about when configuring a service on a system: how is the service accessed externally (routes), what ports do the service(s) use when talking to each other (services), which systems have data and identity that should be consistent across multiple lifecycles/restarts (statefulset) and which systems are simply interchangable workers without state or identity I care about (deployments).

The yaml files in the templates directory set up the routes and services and parameterize the Docker image to run in a specific way. If you read the yaml files, you'll see them setting various environment variables: this configures the Docker image to run with environment specific settings.

When you have your OpenShift environment set-up and available for interaction with the oc command, cd into the templates subdirectory, take a look at the default sizings in the statefulset and deployment files (In particular, look at the size of the storage claims, the number of cpu cores and the amount of memory assigned) and create your instance as follows:

• oc apply -f service-jenkins-http.yaml
• oc apply -f service-jenkins-jnlp.yaml
• oc apply -f route-jenkins-http.yaml

From below, pick one (ephemeral (deployment) or persistent (statefulset)):

• oc apply -f statefulset-jenkins.yaml
• oc apply -f deployment-jenkins.yaml

Note that the defaults currently defined in the yaml files are sized for a medium scale real-world deployment; That means about 4GiB of RAM and about 2 cores of CPU available. If you're just playing around, feel free to lower these to whatever you think you can get away with. Bear in mind that as a general rule, you need to assign double the amount of ram to a pod compared to the amount of ram you assign to the JVM using the -Xms and -Xmx parameters. Finally, keep in mind that your persistent storage classes in your OpenShift environment might be named differently than the ones mentioned in the yaml files. To check names that would work in your cluster, issue a oc get sc command which will show the available storage classes to you.

⁠Environment Variables and Arguments

The Docker image can be parameterized at build and runtime with various arguments and environment variables. Arguments (the ARG keyword in a Dockerfile) are things which exist at build time (i.e, during docker build). Environment variables exist during build and runtime (i.e, also during docker run).

⁠ENV PROXY_HOST

Default: none

Specifies a proxy host that can be used during build time to make the image use a proxy as widely as possible. Together with PROXY_PORT, passed to environment as http_proxy,https_proxy,HTTP_PROXY and HTTPS_PROXY. Also passed to Java via JAVA_TOOL_OPTIONS. Example value: proxy.example.com.

⁠ENV PROXY_PORT

Default: none

The port on which the proxy is listening. For example 8080.

⁠ENV PROXY_NONE

Default: none

Allows one to explicitly specify a comma-separated list of IP addresses and (partial) hostnames which should not be accessed using a proxy. You can partially specify a hostname as follows: .example.com, which would match all hosts ending in .example.com. Example value: localhost,127.0.0.1,.example.com. Sets the environment variables no_proxy and NO_PROXY.

⁠ENV JAVA_TOOL_OPTIONS

Default: -XX:+UseConcMarkSweepGC -XX:InitialRAMPercentage=60.0 -XX:MaxRAMPercentage=80.0 -XX:MinHeapFreeRatio=25 -XX:MaxHeapFreeRatio=50 -Dsun.zip.disableMemoryMapping=true. If you want to enable proxy settings on the Java level, be sure to add: -Dhttp.proxyHost=$PROXY_HOST -Dhttp.proxyPort=$PROXY_PORT -Dhttps.proxyHost=$PROXY_HOST -Dhttps.proxyPort=$PROXY_PORT

Can be used to set a selection of JVM parameters.

⁠ENV GIT_VERSION

Default: 2.22.1

Sets the git version to fetch, compile and use as default.

⁠ENV JENKINS_HOME

Default: /var/lib/jenkins

The home directory of the Jenkins installation. Don't change this, will definitely give unexpected results if changed.

⁠ENV JENKINS_MAIL_HOST

Default: localhost

The hostname of a reachable SMTP server.

⁠ENV JENKINS_MAIL_PORT

Default: 25

The port of the reachable SMTP server set in JENKINS_MAIL_HOST.

⁠ENV JENKINS_RPM_VERSION

Default: 2.176.3-1.1

The specific stable RHEL RPM of Jenkins used.

⁠JENKINS_SHARED_LIBRARY_ENABLED

Default: true

Indicates wether to enable Jenkins shared library functionality. This feature expects to find a repository at a given URL (tested with git:// and https:// urls) which has a top-level directory called vars. In that directory are a bunch of Groovy scripts that make up the generic parts of the pipeline.

Note: the RAAF jenkins repository contains the vars top-level directory which in turn contains our default Jenkins Shared Libraries, and that is also the default shared library location.

However, if you want, you can store that code in your own git repository and point to that using the environment variables JENKINS_SHARED_LIBRARY_REPOSITORY and JENKINS_SHARED_LIBRARY_CREDENTIALID explained below.

Possible values: true, false.

⁠JENKINS_SHARED_LIBRARY_REPOSITORY

Default: https://github.com/raaftech/jenkins.git

The default Jenkins Shared Library location. Should contain a top-level directory called vars. For an example, see the vars directory in this repository.

⁠JENKINS_SHARED_LIBRARY_CREDENTIALID

Default: none

Not all repositories are publicly accessible. If you have a repository that requires an SSH public key or some other credential to access, give the name of that credential here.

Note: this is specifically about a Jenkins Credential ID, which you can create programatically or via the Jenkins GUI.

We often simply use the identifier jenkins which then would match a credential named jenkins containing/referencing an SSH key, which jenkins would then use to access the shared library repository.

⁠ENV JENKINS_SERVICE_NAME

Default: localhost

The name of the Jenkins service.

⁠ENV JENKINS_UC

Default: https://updates.jenkins.io

The Jenkins update site to use.

⁠ENV JENKINS_URL_SCHEME

Default: http

The Jenkins URL scheme to use. Applies to the Jenkins service running on port 8080, and specifically about how it is reached. Can be http or https.

⁠ENV JENKINS_VERSION

Default: 2

The Jenkins major version.

⁠ENV LISTENER_PORT

Default: 8080

The port on which Jenkins is listening.

⁠ENV OPENSHIFT_BUILD_NAMESPACE

Default: none

The name of the OpenShift namespace/project hosting the jenkins instance. For example: tools.

⁠ENV OPENSHIFT_DOMAIN_NAME

Default: none

The top/base of the OpenShift URL hosting the jenkins instance. For example: openshift.example.com.

⁠OPENSHIFT_JENKINS_SETUP_CREDENTIALS

Default: false

Indicates whether or not to set up OpenShift backed credentials. This will assume an OpenShift secret to exist which would be mounted under /var/lib/jenkins/ssh-keys. This location would at the least contain a jenkins-ssh-key entry which would be an SSH private key. This secret would have to exist within the same project (namespace) as the Jenkins container instance.

Possible values: true, false.

⁠OPENSHIFT_SUPPORTED_TEMPLATES

Default: some-template-you-made,some-other-openshift-template

A comma-separated list of OpenShift Templates⁠ you support for deploying and running your artifacts on OpenShift.

⁠OPENSHIFT_TARGET_PROJECTS

Default: some-dev-project,some-test-project,etc

A list of OpenShift Projects⁠ you consider valid deployment targets. When you deploy an application to OpenShift, it would need to be deployed within a project. This list would constrain into which projects your application would be allowed to deploy. Note that we support multi-cluster aware environments. You can in that case specify your target namespaces as follows some-devel@dta, some-tests@dta, some-other@prd. The names after the @ are then the names of the cluster configurations configured in the Jenkins OpenShift Client Plugin⁠. If you don't specify any @, deployment will happen using a cluster configuration named default.

⁠SONAR_SERVICE_ENABLED

Default: false

Indicates wether or not to enable the Sonar Analysis stage. Would require a Sonarqube service and a valid access token (see below).

Possible values: true, false.

⁠SONAR_SERVICE_TOKEN

Default: none

A valid Sonarqube API token used to access the Sonarqube analysis service.

⁠SONAR_SERVICE_URL

Default: http://localhost:9000

Where Sonarqube is running.