This documentation will help you getting Jenkins X installed on OpenShift with minimum supported features as it’s still a work in progress.
Features like Vault integration and Long Term Storage for logs and artifacts are still not supported.
The OpenShift installation documentation will be split in two categories:
- Installing OpenShift with admin permissions.
- Installing OpenShift with restricted permissions.
Here are some recommendations to hopefully get you started. If you hit any issues please join our community we can hopefully help you.
Please set your provider to
openshift via this in your
clusterConfig: provider: openshift
With OpenShift, during the installation with Ansible, you are asked to provide an existing domain, the management of Routes is done directly by the cluster.
This means that, even if
nginx-ingress-controller is installed, it will not be taken into account when managing routes.
To make Jenkins X work with your
Routes and your defined cluster
Domain, you will need to modify the
jx-requirements.yml file like this:
ingress: domain: <your_openshift_domain> exposer: Route
ExposeController will be configured to use Routes with the domain that you provided.
As the domain will be created and managed by the cluster before Jenkins X is installed, the domain will need to be secured independently.
This means that the usual Jenkins X
cert-manager integration will do nothing on OpenShift.
If you need your OpenShift domain to be secured, you will need to manage
cert-manager and your
External Docker Registry
Right now, the supported way to store your docker images is using an external Docker registry like Docker Hub.
To configure it, you’ll need to modify
clusterConfig: registry: docker.io
During the boot process, you will be asked
Do you want to configure non default Docker Registry?. You’ll need to answer yes and provide extra information to connect to Docker Hub.
? Docker Registry Url https://index.docker.io/v1/ ? Docker Registry username <your_dockerhub_username> ? Docker Registry password [? for help] <your_dockerhub_password> ? Docker Registry email <your_dockerhub_email>
We recommend starting with the most simple possible installation and get that working, then gradually try to be more complex. e.g. start off by ignoring these features:
- cloud storage for artifacts
Then once you have something working, incrementally try enabling each of those in turn.
Installing Jenkins X with admin rights
If you have admin rights in your OpenShift cluster and no restrictions to use cluster-wide permissions on services, this will be the preferred way to proceed.
You’ll simply need to modify the
jx-requirements.yml file with the recommended configuration explained above and run
Installing Jenkins X with restricted permissions
While the preferred way to install Jenkins X is with admin rights, OpenShift is aimed for the enterprise user.
This usually means having very limited permissions like not being able to create namespaces, not being able to use cluster-wide permissions etc.
In this case, the installation will need to be split in two phases:
- Cluster admin phase
- Restricted permissions phase
Your user may have admin rights and still want to install Jenkins X with limited permissions, so there will just be a phase in this case, but it will need to be configured to let Jenkins X know how to install itself.
In order to let Jenkins X know that it should install all of its resources with limited permissions, you’ll need to edit
clusterConfig: strictPermissions: true
What this flag will do is the following:
It will default to
It will avoid creating any resource that needs to have cluster level permissions.
It will create additional
Rolesin configured namespaces so certain controllers can work on different namespaces like
It will use the
EnvironmentRoleBindingsto copy the
tekton-botrole to configured namespaces.
For now, it also comes with a limitation: Previews will not work on this kind of cluster. We are working on enabling them using a different mechanism.
Cluster Admin phase
This phase will need to be executed by an user with cluster-admin role or with enough permissions to install
Jenkins X CRDS:
The admin will need to install Jenkins X
CustomResourceDefinitions by executing:
jx upgrade crd
These manifest files will need to be executed in order:
- Tekton CRDS:
kubectl apply --wait -f https://raw.githubusercontent.com/jenkins-x/jenkins-x-boot-config/master/kubeProviders/openshift/templates/tekton-crds.yaml
kubectl apply --wait -f https://raw.githubusercontent.com/jenkins-x/jenkins-x-boot-config/master/kubeProviders/openshift/templates/namespaces.yaml
- Service Accounts
kubectl apply --wait -f https://raw.githubusercontent.com/jenkins-x/jenkins-x-boot-config/master/kubeProviders/openshift/templates/service-accounts.yaml
- JX Admin Role
kubectl apply --wait -f https://raw.githubusercontent.com/jenkins-x/jenkins-x-boot-config/master/kubeProviders/openshift/templates/jx-admin-role.yaml
- ControllerBuild SecurityContextConstraint
kubectl apply --wait -f https://raw.githubusercontent.com/jenkins-x/jenkins-x-boot-config/master/kubeProviders/openshift/templates/controller-build-scc.yaml
After running these manifests, the admin will need to provide an user with the
jx-admin role in different namespaces:
oc adm policy add-role-to-user jx-admin <username> --role-namespace jx --namespace jx oc adm policy add-role-to-user jx-admin <username> --role-namespace jx-staging --namespace jx-staging oc adm policy add-role-to-user jx-admin <username> --role-namespace jx-production --namespace jx-production
Restricted permissions phase
After the cluster admin has created all the necessary resources, the restricted permissions phase can begin.
This can now be executed by the user that was assigned the
jx-admin role in the Cluster Admin phase.
Just one more small change is needed.
There are certain steps within
jenkins-x.yaml that will fail to execute in this phase. Right now, there’s no way to conditionally skip steps so these steps will need to be manually removed from the file.
These steps are:
Once this is done, the installation can proceed as usual, by executing:
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.