Chapter 4. Other Images

You can manage Jenkins authentication in two ways:

$ oc new-app -e \
    JENKINS_PASSWORD=<password> \
    openshift/jenkins-2-centos7

The Jenkins server can be configured with the following environment variables:

If you are going to run Jenkins somewhere other than as a deployment within your same project, you will need to provide an access token to Jenkins to access your project.

The token field contains the token value Jenkins needs to access the project.

The Jenkins image can be run with mounted volumes to enable persistent storage for the configuration:

To customize the official OpenShift Container Platform Jenkins image, you have two options:

You can use S2I to copy your custom Jenkins Jobs definitions, additional plug-ins or replace the provided config.xml file with your own, custom, configuration.

In order to include your modifications in the Jenkins image, you need to have a Git repository with the following directory structure:

pluginId:pluginVersion

The contents of the configuration/ directory will be copied into the /var/lib/jenkins/ directory, so you can also include additional files, such as credentials.xml, there.

The following is an example build configuration that customizes the Jenkins image in OpenShift Container Platform:

apiVersion: v1
kind: BuildConfig
metadata:
  name: custom-jenkins-build
spec:
  source:                       1
    git:
      uri: https://github.com/custom/repository
    type: Git
  strategy:                     2
    sourceStrategy:
      from:
        kind: ImageStreamTag
        name: jenkins:latest
        namespace: openshift
    type: Source
  output:                       3
    to:
      kind: ImageStreamTag
      name: custom-jenkins:latest

The OpenShift Container Platform Jenkins image includes the pre-installed Kubernetes plug-in that allows Jenkins agents to be dynamically provisioned on multiple container hosts using Kubernetes and OpenShift Container Platform.

To use the Kubernetes plug-in, OpenShift Container Platform provides five images suitable for use as Jenkins agents: the Base, Maven, and Node.js images. See Jenkins Agents for more information.

Both the Maven and Node.js agent images are automatically configured as Kubernetes Pod Template images within the OpenShift Container Platform Jenkins image’s configuration for the Kubernetes plug-in. That configuration includes labels for each of the images that can be applied to any of your Jenkins jobs under their "Restrict where this project can be run" setting. If the label is applied, execution of the given job will be done under an OpenShift Container Platform pod running the respective agent image.

The Jenkins image also provides auto-discovery and auto-configuration of additional agent images for the Kubernetes plug-in. With the OpenShift Sync plug-in, the Jenkins image on Jenkins start-up searches within the project that it is running, or the projects specifically listed in the plug-in’s configuration for the following:

When it finds an image stream with the appropriate label, or image stream tag with the appropriate annotation, it generates the corresponding Kubernetes plug-in configuration so you can assign your Jenkins jobs to run in a pod running the container image provided by the image stream.

The name and image references of the image stream or image stream tag are mapped to the name and image fields in the Kubernetes plug-in pod template. You can control the label field of the Kubernetes plug-in pod template by setting an annotation on the image stream or image stream tag object with the key slave-label. Otherwise, the name is used as the label.

When it finds a ConfigMap with the appropriate label, it assumes that any values in the key-value data payload of the ConfigMap contains XML consistent with the config format for Jenkins and the Kubernetes plug-in pod templates. A key differentiator to note when using ConfigMaps, instead of image streams or image stream tags, is that you can control all the various fields of the Kubernetes plug-in pod template.

The following is an example ConfigMap:

kind: ConfigMap
apiVersion: v1
metadata:
  name: jenkins-agent
  labels:
    role: jenkins-slave
data:
  template1: |-
    <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
      <inheritFrom></inheritFrom>
      <name>template1</name>
      <instanceCap>2147483647</instanceCap>
      <idleMinutes>0</idleMinutes>
      <label>template1</label>
      <serviceAccount>jenkins</serviceAccount>
      <nodeSelector></nodeSelector>
      <volumes/>
      <containers>
        <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          <name>jnlp</name>
          <image>openshift/jenkins-agent-maven-35-centos7:v3.10</image>
          <privileged>false</privileged>
          <alwaysPullImage>true</alwaysPullImage>
          <workingDir>/tmp</workingDir>
          <command></command>
          <args>${computer.jnlpmac} ${computer.name}</args>
          <ttyEnabled>false</ttyEnabled>
          <resourceRequestCpu></resourceRequestCpu>
          <resourceRequestMemory></resourceRequestMemory>
          <resourceLimitCpu></resourceLimitCpu>
          <resourceLimitMemory></resourceLimitMemory>
          <envVars/>
        </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
      </containers>
      <envVars/>
      <annotations/>
      <imagePullSecrets/>
      <nodeProperties/>
    </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>

After startup, the OpenShift Sync plug-in monitors the API server of OpenShift Container Platform for updates to ImageStreams, ImageStreamTags, and ConfigMaps and adjusts the configuration of the Kubernetes plug-in.

In particular, the following rules will apply:

To use a container image as a Jenkins agent, the image must run the slave agent as an entrypoint. For more details about this, refer to the official Jenkins documentation.

Templates provide parameter fields to define all the environment variables (password) with predefined defaults. OpenShift Container Platform provides templates to make creating a new Jenkins service easy. The Jenkins templates should have been registered in the default openshift project by your cluster administrator during the initial cluster setup. See Loading the Default Image Streams and Templates for more details, if required.

a deployment configuration and a service.

must instantiate the template to be able to use Jenkins:

A fuller sample which achieves a similar goal is available here.

kind: List
apiVersion: v1
items:
- kind: ImageStream
  apiVersion: v1
  metadata:
    name: openshift-jee-sample
- kind: BuildConfig
  apiVersion: v1
  metadata:
    name: openshift-jee-sample-docker
  spec:
    strategy:
      type: Docker
    source:
      type: Docker
      dockerfile: |-
        FROM openshift/wildfly-101-centos7:latest
        COPY ROOT.war /wildfly/standalone/deployments/ROOT.war
        CMD $STI_SCRIPTS_PATH/run
      binary:
        asFile: ROOT.war
    output:
      to:
        kind: ImageStreamTag
        name: openshift-jee-sample:latest
- kind: BuildConfig
  apiVersion: v1
  metadata:
    name: openshift-jee-sample
  spec:
    strategy:
      type: JenkinsPipeline
      jenkinsPipelineStrategy:
        jenkinsfile: |-
          node("maven") {
            sh "git clone https://github.com/openshift/openshift-jee-sample.git ."
            sh "mvn -B -Popenshift package"
            sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war"
          }
    triggers:
    - type: ConfigChange

It is also possible to override the specification of the dynamically created Jenkins agent Pod. The following is a modification to the above example which overrides the container memory and specifies an environment variable:

kind: BuildConfig
apiVersion: v1
metadata:
  name: openshift-jee-sample
spec:
  strategy:
    type: JenkinsPipeline
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        podTemplate(label: "mypod", 1
                    cloud: "openshift", 2
                    inheritFrom: "maven", 3
                    containers: [
            containerTemplate(name: "jnlp", 4
                              image: "openshift/jenkins-agent-maven-35-centos7:v3.10", 5
                              resourceRequestMemory: "512Mi", 6
                              resourceLimitMemory: "512Mi", 7
                              envVars: [
              envVar(key: "CONTAINER_HEAP_PERCENT", value: "0.25") 8
            ])
          ]) {
          node("mypod") { 9
            sh "git clone https://github.com/openshift/openshift-jee-sample.git ."
            sh "mvn -B -Popenshift package"
            sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war"
          }
        }
  triggers:
  - type: ConfigChange

By default the pod is deleted when the build completes. This behavior can be modified via the plug-in or within a pipeline Jenkinsfile - see Agent Pod Retention for further details.

For more information on Kubernetes plug-in configuration, see the Kubernetes plug-in documentation.

When deployed by the provided Jenkins Ephemeral or Jenkins Persistent templates, the default memory limit is 512MiB.

See Sizing OpenJDK on OpenShift Container Platform for background information on tuning the JVM used by Jenkins.

For memory efficiency, by default the Jenkins image dynamically uses a 32-bit JVM if running in a container with a memory limit under 2GiB. This behavior can be overridden by the OPENSHIFT_JENKINS_JVM_ARCH environment variable.

By default the Jenkins JVM uses 50% of the container memory limit for its heap. This value can be modified by the CONTAINER_HEAP_PERCENT environment variable. It can also be capped at an upper limit or overridden entirely. See Environment Variables for more details.

Consider that by default all other processes executed in the Jenkins container, such as shell scripts or oc commands run locally from pipelines, are not likely to be able to use more than the remaining 256MiB memory combined without provoking an OOM kill. It is therefore highly recommended that pipelines run external commands in a agent container wherever possible.

It is recommended to specify memory request and limit values on agent containers created by the Jenkins Kubernetes Plug-in. As admin, defaults can be set on a per-agent image basis through the Jenkins configuration. The memory request and limit can also be overridden on a per-container basis as documented above.

You can increase the amount of memory available to Jenkins by overriding the MEMORY_LIMIT paramenter when instantiating the Jenkins Ephemeral or Jenkins Persistent template.

The OpenShift Container Platform Client Plug-in aims to provide a readable, concise, comprehensive, and fluent Jenkins Pipeline syntax for rich interactions with OpenShift Container Platform. The plug-in leverages the oc binary, which must be available on the nodes executing the script.

This plug-in is fully supported and is included in the Jenkins image. It provides:

See the OpenShift Pipeline Builds tutorial and the plug-in’s README for more information.

The OpenShift Container Platform Pipeline Plug-in is a prior integration between Jenkins and OpenShift Container Platform which provides less functionality than the OpenShift Container Platform Client Plug-in. It has been deprecated but continues to work with OpenShift Container Platform versions up to v3.11. For later verions of OpenShift Container Platform, either use the oc binary directly from your Jenkins Pipelines, or use the OpenShift Container Platform Client Plug-in.

See the plug-in’s README for more information.

To facilitate OpenShift Container Platform Pipeline build strategy for integration between Jenkins and OpenShift Container Platform, the OpenShift Sync Plug-in monitors the API server of OpenShift Container Platform for updates to BuildConfigs and Builds that employ the Pipeline strategy and either creates Jenkins Pipeline projects (when a BuildConfig is created) or starts jobs in the resulting projects (when a Build is started).

As noted in Configuring the Jenkins Kubernetes Plug-in, this plug-in can create PodTemplate configurations for the Kubernetes plug-in based on specifically cited ImageStream, ImageStreamTag, or ConfigMap objects defined in OpenShift Container Platform.

This plug-in can now take Secret objects with a label key of credential.sync.jenkins.openshift.io and label value of true and construct Jenkins credentials which are placed in the default global domain within the Jenkins credentials hierarchy. The ID of the credential will be composed of the namespace the Secret is defined in, a hyphen (-), followed by the name of the Secret.

Similar to the handling of ConfigMaps for PodTemplates, the Secret object defined in OpenShift Container Platform is considered the master configuration. Any subsequent updates to the object in OpenShift Container Platform will be applied to the Jenkins credential (overwriting any changes to the credential made in the interim).

Removal of the credential.sync.jenkins.openshift.io property, setting of that property to something other than true, or deletion of the Secret in OpenShift Container Platform will result in deletion of the associated credential in Jenkins.

The type of secret will be mapped to the jenkins credential type as follows:

The Kubernetes plug-in is used to run Jenkins agents as pods on your cluster. The auto-configuration of the Kubernetes plug-in is described in Using the Jenkins Kubernetes Plug-in.

Each Jenkins agent container can be configured with the following environment variables:

A JVM is used in all Jenkins agents to host the Jenkins JNLP agent, as well as to run any Java applications (e.g. javac, Maven or Gradle). See Sizing OpenJDK on OpenShift Container Platform for background information on tuning the JVM used by Jenkins agents.

For memory efficiency, by default the Jenkins image dynamically uses a 32-bit JVM if running in a container with a memory limit under 2GiB. This behavior can be overridden by the OPENSHIFT_JENKINS_JVM_ARCH environment variable. The JVM choice applies by default both for the Jenkins JNLP agent as well as for any other Java processes within the agent container.

By default the Jenkins JNLP agent JVM uses 50% of the container memory limit for its heap. This value can be modified by the CONTAINER_HEAP_PERCENT environment variable. It can also be capped at an upper limit or overridden entirely. See Environment Variables for more details.

Consider that by default any/all other processes executed in the Jenkins agent container, e.g. shell scripts or oc commands run from pipelines, may not be able to use more than the remaining 50% memory limit without provoking an OOM kill.

By default, each further JVM process run in a Jenkins agent container will use up to 25% of the container memory limit for their heap. It may be necessary to tune this for many build workloads. See Sizing OpenJDK on OpenShift Container Platform for more information.

See the Jenkins documentation for information on specifying the memory request and limit of a Jenkins agent container.