Deploy Jenkins on OpenShift 4 with custom OAuth server URL

Environment

• Red Hat OpenShift Container Platform (RHOCP)
  • 4
• Custom hostname and TLS key pair for the oauth-openshift route.
• Jenkins

Issue

• When the custom URL uses a TLS key pair that has not been signed by a globally trusted authority, Jenkins does not trust the OAuth server and does not allow anyone to access the web console.

Resolution

1. Determine the namespace where Jenkins will be deployed.

2. Copy the data in oauth-serving-cert from the openshift-config-managed namespace, and add it to a new ConfigMap in the Jenkins namespace named oauth-serving-cert. Preserve the names of the keys copied from the ConfigMap, and ensure the order of the certificates in the certificate chain.

   $ oc get cm oauth-serving-cert -n openshift-config-managed -o yaml
   [...]
   

3. Download the JSON of the Jenkins template to deploy:

       $ oc get templates -n openshift | grep jenkins
       jenkins-ephemeral                             Jenkins service, without persistent storage....                                    12 (all set)      7
       jenkins-ephemeral-monitored                   Jenkins service, without persistent storage. ...                                   13 (all set)      8
       jenkins-persistent                            Jenkins service, with persistent storage....                                       14 (all set)      8
       jenkins-persistent-monitored                  Jenkins service, with persistent storage. ...                                      15 (all set)      9
   
       $ oc get template jenkins- -n openshift -o json > jenkins-template-custom-oauth.json
   

4. Edit the template JSON to add the following volumes and volume mounts:

    "volumeMounts": [
    	{
    		"mountPath": "/var/lib/jenkins",
    		"name": "${JENKINS_SERVICE_NAME}-data"
    	},
    	{
    		"mountPath": "/etc/pki/ca-trust/source/anchors",
    		"name": "all-ca-certs"
    	}
    ]
   
    <...>
   
    "volumes": [
    	{
    		"name": "${JENKINS_SERVICE_NAME}-data",
    		"persistentVolumeClaim": {
    			"claimName": "${JENKINS_SERVICE_NAME}"
    		}
    	},
    	{
    		"name": "all-ca-certs",
    		"projected": {
    			"sources": [
    				{
    					"configMap": {
    						"name": "${JENKINS_SERVICE_NAME}-trusted-ca-bundle",
    						"items": [
    							{
    								"key": "ca-bundle.crt",
    								"path": "global-ca-bundle.crt"
    							}
    						]
    					}
    				},
    				{
    					"configMap": {
    						"name": "oauth-serving-cert",
    						"items": [
    							{
    								"key": "ca-bundle.crt",
    								"path": "oauth-ca-bundle.crt"
    							}
    						]
    					}
    				}
    			]
    		}
    	}
    ]
   

5. Deploy Jenkins with the modified template:

    $ oc new-app --file=jenkins-template-custom-oauth.json
   

Root Cause

Starting with OpenShift 4.9, it is possible to customize the internal URL for the cluster's OAuth server with its own hostname and TLS key pair, as described in the customizing the internal OAuth server URL topic. OpenShift's Jenkins image includes a plugin that integrates with the OAuth server, enabling OpenShift to manage identity and access for the Jenkins instance (for example, access to the Jenkins web console). This integration is enabled by default in the provided Jenkins templates, as shown in the OpenShift Container Platform OAuth authentication topic.

When the OAuth server is configured with a custom hostname and TLS key pair, Jenkins will not trust the OAuth server if the TLS key pair is self-signed or is signed by a certificate authority that is not globally trusted. See This content is not included.Bug #1991448 for additional information.

Diagnostic Steps

• Check the OpenShift version is 4.9 or higher:

  $ oc version
  [...]
  $ oc get clusterversion
  [...]
  

• Check if the cluster has customized their Ingress configuration to add a custom URL and keypair for the oauth-openshift route:

    apiVersion: config.openshift.io/v1
    kind: Ingress
    metadata:
      name: cluster
    spec:
      componentRoutes:
        - name: oauth-openshift
          namespace: openshift-authentication
          hostname: <custom_hostname> 
          servingCertKeyPairSecret:
            name: <secret_name> 
  

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.