How to Deploy to OpenShift from an External Jenkins Instance

A common scenario I’ve encountered with OpenShift is the need to deploy and undeploy applications on OpenShift through an external Jenkins server. This is an essential requirement when building Deployment Pipelines in order to take advantage of OpenShift advanced automation for provisioning application runtimes.

OpenShift exposes a REST API that can be used to orchestrate creating and disposing gears. A simpler alternative is using the OpenShift Deployer Jenkins Plugin that hides that complexity and uses the REST API internally to create and deploy Java (war and ear) applications on OpenShift as well as removing the gears as part of a Jenkins Job.

Installing OpenShift Deployer Jenkins Plugin

There are several ways to install a plugin on Jenkins. The simplest way is through Jenkins automatic plugin installer. Go to Manage Jenkins > Manage Plugins > Available and enter “OpenShift Deployer” in the filter textbox. Select the checkbox for OpenShift Deployer Plugin and click on Install without Restart. Click on Restart Jenkins on the installation progress screen in order to restart Jenkins when the installation is complete.

OpenShift install

Alternatively you can download the plugin from Jenkins download site and upload it manually in Manage Jenkins > Manage Plugins > Advanced.

Plugin Configuration

In order to deploy to OpenShift, first you need to define the OpenShift environments you want to use for deployment. Go to Manage Jenkins > Configure System and scroll down to the OpenShift section.

SSH keys are essential when working with OpenShift. If no SSH keys exist on the Jenkins server, follow these instructions to generate a pair:

su jenkins -s /bin/sh
ssh-keygen -t rsa

Next, you’ll be asked to enter a passphrase. It is recommended to enter a very strong passphrase. Alternatively press enter to use an empty passphrase.

Add an OpenShift Server block for each OpenShift environment you want to deploy to by specifying a name, broker address, username and password. If using OpenShift Online, enter openshift.redhat.com (default value) as the Broker Address otherwise, enter the OpenShift Enterprise Broker address.

OpenShift Plugin Configuration

 

Click on Check Login to verify authentication. If successful, you can upload your SSH public key to the OpenShift server by clicking on Upload SSH Keys. Make sure that the SSH Public Key Path value reflects the correct path to the public key on the Jenkins server filesystem.

Job Configuration

Create a Jenkins Job for your project or go the job’s Configure screen in order to add a post-build step for deploying an application onto OpenShift. Click on Add post-build step and choose OpenShift: Deploy Application.

OpenShift Add Post-build Step

 

Select an OpenShift environment from the list of environments you have defined in the Jenkins global configuration. Enter the application name, the domain (namespace) for the application, the cartridges to be used and the gear profile (small, medium, etc) for the OpenShift gear. Note that the domain needs to already exist in the selected OpenShift environment.

Enter the path to your deployable archives (war or ear) in Deployment Package(s) textbox. If building your project with Maven, the packages will be built in the target directory. Another option is to enter the URL to the archive for example in the artifact repository (e.g. Nexus).

OpenShift deploy-buildstep

When the Job gets triggered, the plugin checks the selected OpenShift environment for a gear with the specified name in the specified domain. If it exists, the deployment archives will be deployed to it. Otherwise, the plugin will first create the gear and then deploy the application onto it.

OpenShift: Delete Application build-step can be used to remove an existing application (gear) from the selected OpenShift environment. It is useful for implementing practises like Immutable Servers where you create a new gear before running your tests and then tear down the gear after the tests are complete.

Categories
JBoss, Jenkins
Tags
  • Lorenzo González

    You can deploy by using Apache Ant and simply running Ant script from Jenkins.
    I have developed many ant task for openshift.
    https://github.com/logongas/antopenshift

  • James Owen

    Is there any plans for the deployment plugin to support fat jar? At the moment I have to jump through hoops to deploy a fatJar as I do not use Ear/War

  • Néstor Acevedo

    How it works for a PHP application? What I get is ERROR: [OPENSHIFT] No Deployments found! (configuredValue: /) setting up deployment package as / but obviously if I set target/ as deployment package I get a folder not exists error

  • Karthik Marupeddi

    ERROR: [OPENSHIFT] No Deployments found! (configuredValue: /)
    ERROR: [OPENSHIFT] hudson.AbortException
    I get above error when trying to execute on openshift account.