×

OpenShift Container Platform provides a container image for running Jenkins. This image provides a Jenkins server instance, which can be used to set up a basic flow for continuous testing, integration, and delivery.

The image is based on the Red Hat Universal Base ImagesĀ (UBI).

OpenShift Container Platform follows the LTS release of Jenkins. OpenShift Container Platform provides an image that contains Jenkins 2.x.

The OpenShift Container Platform Jenkins images are available on Quay.io or registry.redhat.io.

For example:

$ podman pull registry.redhat.io/ocp-tools-4/jenkins-rhel8:<image_tag>

To use these images, you can either access them directly from these registries or push them into your OpenShift Container Platform container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your OpenShift Container Platform resources can then reference the image stream.

But for convenience, OpenShift Container Platform provides image streams in the openshift namespace for the core Jenkins image as well as the example Agent images provided for OpenShift Container Platform integration with Jenkins.

Configuration and customization

You can manage Jenkins authentication in two ways:

  • OpenShift Container Platform OAuth authentication provided by the OpenShift Container Platform Login plug-in.

  • Standard authentication provided by Jenkins.

OpenShift Container Platform OAuth authentication

OAuth authentication is activated by configuring options on the Configure Global Security panel in the Jenkins UI, or by setting the OPENSHIFT_ENABLE_OAUTH environment variable on the Jenkins Deployment configuration to anything other than false. This activates the OpenShift Container Platform Login plug-in, which retrieves the configuration information from pod data or by interacting with the OpenShift Container Platform API server.

Valid credentials are controlled by the OpenShift Container Platform identity provider.

Jenkins supports both browser and non-browser access.

Valid users are automatically added to the Jenkins authorization matrix at log in, where OpenShift Container Platform roles dictate the specific Jenkins permissions that users have. The roles used by default are the predefined admin, edit, and view. The login plug-in executes self-SAR requests against those roles in the project or namespace that Jenkins is running in.

Users with the admin role have the traditional Jenkins administrative user permissions. Users with the edit or view role have progressively fewer permissions.

The default OpenShift Container Platform admin, edit, and view roles and the Jenkins permissions those roles are assigned in the Jenkins instance are configurable.

When running Jenkins in an OpenShift Container Platform pod, the login plug-in looks for a config map named openshift-jenkins-login-plugin-config in the namespace that Jenkins is running in.

If this plug-in finds and can read in that config map, you can define the role to Jenkins Permission mappings. Specifically:

  • The login plug-in treats the key and value pairs in the config map as Jenkins permission to OpenShift Container Platform role mappings.

  • The key is the Jenkins permission group short ID and the Jenkins permission short ID, with those two separated by a hyphen character.

  • If you want to add the Overall Jenkins Administer permission to an OpenShift Container Platform role, the key should be Overall-Administer.

  • To get a sense of which permission groups and permissions IDs are available, go to the matrix authorization page in the Jenkins console and IDs for the groups and individual permissions in the table they provide.

  • The value of the key and value pair is the list of OpenShift Container Platform roles the permission should apply to, with each role separated by a comma.

  • If you want to add the Overall Jenkins Administer permission to both the default admin and edit roles, as well as a new Jenkins role you have created, the value for the key Overall-Administer would be admin,edit,jenkins.

The admin user that is pre-populated in the OpenShift Container Platform Jenkins image with administrative privileges is not given those privileges when OpenShift Container Platform OAuth is used. To grant these permissions the OpenShift Container Platform cluster administrator must explicitly define that user in the OpenShift Container Platform identity provider and assigns the admin role to the user.

Jenkins users' permissions that are stored can be changed after the users are initially established. The OpenShift Container Platform Login plug-in polls the OpenShift Container Platform API server for permissions and updates the permissions stored in Jenkins for each user with the permissions retrieved from OpenShift Container Platform. If the Jenkins UI is used to update permissions for a Jenkins user, the permission changes are overwritten the next time the plug-in polls OpenShift Container Platform.

You can control how often the polling occurs with the OPENSHIFT_PERMISSIONS_POLL_INTERVAL environment variable. The default polling interval is five minutes.

The easiest way to create a new Jenkins service using OAuth authentication is to use a template.

Jenkins authentication

Jenkins authentication is used by default if the image is run directly, without using a template.

The first time Jenkins starts, the configuration is created along with the administrator user and password. The default user credentials are admin and password. Configure the default password by setting the JENKINS_PASSWORD environment variable when using, and only when using, standard Jenkins authentication.

Procedure
  • Create a Jenkins application that uses standard Jenkins authentication:

    $ oc new-app -e \
        JENKINS_PASSWORD=<password> \
        ocp-tools-4/jenkins-rhel8

Jenkins environment variables

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

Variable Definition Example values and settings

OPENSHIFT_ENABLE_OAUTH

Determines whether the OpenShift Container Platform Login plug-in manages authentication when logging in to Jenkins. To enable, set to true.

Default: false

JENKINS_PASSWORD

The password for the admin user when using standard Jenkins authentication. Not applicable when OPENSHIFT_ENABLE_OAUTH is set to true.

Default: password

JAVA_MAX_HEAP_PARAM, CONTAINER_HEAP_PERCENT, JENKINS_MAX_HEAP_UPPER_BOUND_MB

These values control the maximum heap size of the Jenkins JVM. If JAVA_MAX_HEAP_PARAM is set, its value takes precedence. Otherwise, the maximum heap size is dynamically calculated as CONTAINER_HEAP_PERCENT of the container memory limit, optionally capped at JENKINS_MAX_HEAP_UPPER_BOUND_MB MiB.

By default, the maximum heap size of the Jenkins JVM is set to 50% of the container memory limit with no cap.

JAVA_MAX_HEAP_PARAM example setting: -Xmx512m

CONTAINER_HEAP_PERCENT default: 0.5, or 50%

JENKINS_MAX_HEAP_UPPER_BOUND_MB example setting: 512 MiB

JAVA_INITIAL_HEAP_PARAM, CONTAINER_INITIAL_PERCENT

These values control the initial heap size of the Jenkins JVM. If JAVA_INITIAL_HEAP_PARAM is set, its value takes precedence. Otherwise, the initial heap size is dynamically calculated as CONTAINER_INITIAL_PERCENT of the dynamically calculated maximum heap size.

By default, the JVM sets the initial heap size.

JAVA_INITIAL_HEAP_PARAM example setting: -Xms32m

CONTAINER_INITIAL_PERCENT example setting: 0.1, or 10%

CONTAINER_CORE_LIMIT

If set, specifies an integer number of cores used for sizing numbers of internal JVM threads.

Example setting: 2

JAVA_TOOL_OPTIONS

Specifies options to apply to all JVMs running in this container. It is not recommended to override this value.

Default: -XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true

JAVA_GC_OPTS

Specifies Jenkins JVM garbage collection parameters. It is not recommended to override this value.

Default: -XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90

JENKINS_JAVA_OVERRIDES

Specifies additional options for the Jenkins JVM. These options are appended to all other options, including the Java options above, and may be used to override any of them if necessary. Separate each additional option with a space; if any option contains space characters, escape them with a backslash.

Example settings: -Dfoo -Dbar; -Dfoo=first\ value -Dbar=second\ value.

JENKINS_OPTS

Specifies arguments to Jenkins.

INSTALL_PLUGINS

Specifies additional Jenkins plug-ins to install when the container is first run or when OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS is set to true. Plug-ins are specified as a comma-delimited list of name:version pairs.

Example setting: git:3.7.0,subversion:2.10.2.

OPENSHIFT_PERMISSIONS_POLL_INTERVAL

Specifies the interval in milliseconds that the OpenShift Container Platform Login plug-in polls OpenShift Container Platform for the permissions that are associated with each user that is defined in Jenkins.

Default: 300000 - 5 minutes

OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG

When running this image with an OpenShift Container Platform persistent volume (PV) for the Jenkins configuration directory, the transfer of configuration from the image to the PV is performed only the first time the image starts because the PV is assigned when the persistent volume claim (PVC) is created. If you create a custom image that extends this image and updates the configuration in the custom image after the initial startup, the configuration is not copied over unless you set this environment variable to true.

Default: false

OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS

When running this image with an OpenShift Container Platform PV for the Jenkins configuration directory, the transfer of plug-ins from the image to the PV is performed only the first time the image starts because the PV is assigned when the PVC is created. If you create a custom image that extends this image and updates plug-ins in the custom image after the initial startup, the plug-ins are not copied over unless you set this environment variable to true.

Default: false

ENABLE_FATAL_ERROR_LOG_FILE

When running this image with an OpenShift Container Platform PVC for the Jenkins configuration directory, this environment variable allows the fatal error log file to persist when a fatal error occurs. The fatal error file is saved at /var/lib/jenkins/logs.

Default: false

AGENT_BASE_IMAGE

Setting this value overrides the image used for the jnlp container in the sample Kubernetes plug-in pod templates provided with this image. Otherwise, the image from the jenkins-agent-base-rhel8:latest image stream tag in the openshift namespace is used.

Default: image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base-rhel8:latest

JAVA_BUILDER_IMAGE

Setting this value overrides the image used for the java-builder container in the java-builder sample Kubernetes plug-in pod templates provided with this image. Otherwise, the image from the java:latest image stream tag in the openshift namespace is used.

Default: image-registry.openshift-image-registry.svc:5000/openshift/java:latest

NODEJS_BUILDER_IMAGE

Setting this value overrides the image used for the nodejs-builder container in the nodejs-builder sample Kubernetes plug-in pod templates provided with this image. Otherwise, the image from the nodejs:latest image stream tag in the openshift namespace is used.

Default: image-registry.openshift-image-registry.svc:5000/openshift/nodejs:latest

JAVA_FIPS_OPTIONS

Setting this value controls how the JVM operates when running on a FIPS node. For more information, see Configure OpenJDK 11 in FIPS mode.

Default: -Dcom.redhat.fips=false

Providing Jenkins cross project access

If you are going to run Jenkins somewhere other than your same project, you must provide an access token to Jenkins to access your project.

Procedure
  1. Identify the secret for the service account that has appropriate permissions to access the project Jenkins must access:

    $ oc describe serviceaccount jenkins
    Example output
    Name:       default
    Labels:     <none>
    Secrets:    {  jenkins-token-uyswp    }
                {  jenkins-dockercfg-xcr3d    }
    Tokens:     jenkins-token-izv1u
                jenkins-token-uyswp

    In this case the secret is named jenkins-token-uyswp.

  2. Retrieve the token from the secret:

    $ oc describe secret <secret name from above>
    Example output
    Name:       jenkins-token-uyswp
    Labels:     <none>
    Annotations:    kubernetes.io/service-account.name=jenkins,kubernetes.io/service-account.uid=32f5b661-2a8f-11e5-9528-3c970e3bf0b7
    Type:   kubernetes.io/service-account-token
    Data
    ====
    ca.crt: 1066 bytes
    token:  eyJhbGc..<content cut>....wRA

    The token parameter contains the token value Jenkins requires to access the project.

Jenkins cross volume mount points

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

  • /var/lib/jenkins is the data directory where Jenkins stores configuration files, including job definitions.

Customizing the Jenkins image through source-to-image

To customize the official OpenShift Container Platform Jenkins image, you can use the image as a source-to-image (S2I) builder.

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

To include your modifications in the Jenkins image, you must have a Git repository with the following directory structure:

plugins

This directory contains those binary Jenkins plug-ins you want to copy into Jenkins.

plugins.txt

This file lists the plug-ins you want to install using the following syntax:

pluginId:pluginVersion
configuration/jobs

This directory contains the Jenkins job definitions.

configuration/config.xml

This file contains your custom Jenkins configuration.

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