Introduction to Deployments and Rollbacks on OpenShift

Rollback your code on OpenShift

Great news fellow developers, OpenShift now supports deployment history complete with the ability to rollback to a previous version of your application. Why is this important? I will be the first to admit to having pushed things to production only to find a new bug that is critical in nature and has to be fixed immediately. The most obvious way to handle this is to rollback the application code to the last known working state while developers can work to resolve the defect in the software. Throughout my years in development and managing system administrators, I have seen various methods to solve this problem including versioning RPMS and keeping them in a repository to backing up the gold build of the .war or .ear file in Javaland. During this blog post, I will introduce you to deployment and rollback strategy we have implement for all users of the OpenShift PaaS.

Before we get started, let's get some prerequisites out of the way. In order to follow along with this blog post, you will need to have an account for OpenShift and create a demo application to try this out on. If you already have an OpenShift account and have the RHC client tools installed, you can skip down to step 3.

Step 1: Create an OpenShift account

If you don’t already have an OpenShift account, head on over to the website and sign up. It is completely free and Red Hat gives every user three free Gears on which to run your applications. At the time of this writing, the combined resources allocated for each user is 1.5 GB of memory and 3 GB of disk space.

Step 2: Install the RHC client tools

Note: If you would rather watch a screencast of this step, check out the following videos where I demo how to install the client tools.

Windows
Linux Ubuntu
Linux Fedora
OSX

The OpenShift client tools are written in a very popular programming language called Ruby. With OSX 10.6 or later and most Linux distributions, ruby is installed by default so installing the client tools is a snap. Simply issue the following command on your terminal application:

$ sudo gem install rhc

Step 3: Create a demo application

In order to try out the new deployment and rollback system, we will need to create an application to play around with. We will start by creating a PHP application but this process will hold true for other languages that OpenShift supports. To create our application, issue the following command:

$ rhc app create demo php-5.3

This will create an application container for us, called a gear, and setup all of the required SELinux policies and cgroup configuration. OpenShift will also setup a private git repository for you and propogate your DNS out world wide. This whole process should take about 30 seconds.

Step 4: Modifying application configuration to enable tracking deployments

By default, OpenShift will only track the last deployment of your application. In order to be able to rollback to a previous version of your application code, we need to configure the demo application we created in step 2 to track multiple deployments of our code base. To accomplish this, change to your application directory and modify the configuration with the following commands:

$ cd demo
$ rhc app-configure --keep-deployments 10

The above command will alert OpenShift that we want to track the last 10 deployments of our application.

Note: If you get an error message saying invalid syntax, this is because you are running an older version of the client tools on your machine. The rhc gem that contains the deployment functionality was released on November 6, 2013. If your rhc gem install is older than that, simply run a gem update rhc to get the latest version.

Step 5: List our deployments and create a new one

To view a list of your application deployment history, issue the following command:

$ rhc deployment-list

If the above command is executed correctly, you should see one deployment in your history.

9:35 PM, deployment c22fd97a

Obviously, the information you see will look slightly different including the time of the deployment and the deployment hash. The reason you have a deployment already in your history is that when you created the application in step 3, a template application was deployed to your OpenShift gear. For example, if you view your application in a browser at this point, you will see this deployment which includes the getting started page at your domain.

Let's create a new file and deploy it to see deployments in action. Ensure that you are in your application root directory and enter in the following commands:

$ cd php
$ echo "Hello deployment 1" >> hello.html
$ git add .
$ git commit -am "Creating hello text file";
$ git push

If you have used OpenShift in the past, you will notice a few new bits of information provided to you when you performed the git push. Namely, the platform will display the deployment ID as well activating the deployment. The output should look similar to this:

remote: Building git ref 'master', commit f0c569d
remote: Building PHP cartridge
remote: Preparing build for deployment
remote: Deployment id is 9f37d551
remote: Activating deployment
remote: Starting PHP cartridge
remote: Result: success
remote: Activation status: success
remote: Deployment completed with status: success

Verify that your application code was pushed to the production gear by visiting the URL for your application. Open your browser and point the location to:

http://demo-YourNameSpace.rhcloud.com/hello.html

Ensure that you replace YourNameSpace with the correct information for your application. If the deployment was successful, you should see the following displayed in your web browser:

Hello deployment 1

Let's create one more deployment so that we can demonstrate how to properly roll back. Ensure that you are still in the php directory of your application and issue the following commands:

$ echo "Hello deployment 3" > hello.html
$ git commit -am "Modify deployment number";
$ git push

Verify that your application code was pushed to the production gear by visiting the URL for your application. Open your browser and point the location to:

http://demo-YourNameSpace.rhcloud.com/hello.html

Ensure that you replace YourNameSpace with the correct information for your application. If the deployment was successful, you should see the following displayed in your web browser:

Hello deployment 3

Step 6: Rolling back

Oops! In step 5 we made a mistake and accidentally printed "Hello deployment 3" to the user when we meant to say "Hello deployment 2". Because this is a mission critical bug (and they all are -- Am I right?), the powers that be require that we immediately fix the situation. To roll back to our last known good state, we need to list all of our deployments and then reactivate the last known working one while we address the issue. Let's list all of our deployments with the following command:

$ rhc deployment-list

You should see three deployments of your application as follows (with different timestamps and hashes):

9:35 PM, deployment c22fd97a
9:44 PM, deployment 9f37d551
9:50 PM, deployment 2eb3b3e8

To better understand these deployments, let's explain each one.

  1. 9:35 PM, deployment c22fd97a This is the initial deployment that happened when we created our OpenShift application. It included the template web application that is deployed by default.

  2. 9:44 PM, deployment 9f37d551 This deployment contains the addition of the hello.html file that displays "Hello deployment 1" to the user.

  3. 9:50 PM, deployment 2eb3b3e8 This deployment contains the mission critical bug that displays "Hello deployment 3" to the user instead of "Hello deployment 2".

At this point, we want to rollback our application code to hash 9f37d551 that was deployed at 9:44 PM. To roll our code back, enter the following command:

$ rhc deployment-activate 9f37d551

You should see the following output:

Activating deployment '9f37d551' on application demo ...
Activating deployment
Stopping PHP cartridge
Waiting for stop to finish
Starting PHP cartridge
Success

BOOM! We just rolled back our application code to the last known good state. At this point, you can also fast-forward to the last deployment with a hash of 2eb3b3e8 if you desire. If you run the following command:

$ rhc deployment-list

You will see information about the rollback that happened. It should look similar to this:

9:35 PM, deployment c22fd97a
9:44 PM, deployment 9f37d551
9:50 PM, deployment 2eb3b3e8 (rolled back)
10:00 PM, deployment 9f37d551 (rollback to 9:44 PM)

Changing the default branch

I often get asked if we support the ability to deploy code from a git branch other than master. Well friends, that time has come. Using the rhc app-configure command, you can list the current branch that deployments will happen from.

$ rhc app-configure

And you should see the following output:

demo @ http://demo-onpaas.rhcloud.com/ (uuid: 527b186e4382ecaa7d00003f)
-----------------------------------------------------------------------
Deployment:        auto (on git push)
Keep Deployments:  10
Deployment Type:   git
Deployment Branch: master

Your application 'demo' is configured as listed above.

In order change the branch we want to deploy from, simply issue the following command:

rhc app-configure --deployment-branch mybranch

Verify the change with the following command:

$ rhc app-configure

Disabling automatic deployment

The fun hasn't stopped yet. What if you want to commit and push code to your OpenShift repo but not actually deploy it? No problem, we support that now as well. Just turn off automatic deployment with the following command:

$ rhc app-configure --no-auto-deploy

Verify your new configuration:

$ rhc app-configure

Supporting binary deployments

If you are Java developer, you may be building your .war or .ear file locally and then pushing that to your OpenShift gear. Good news, we also support binary deployment versioning by changing the deployment type. Simply issue the following command:

$ rhc app-configure --deployment-type binary

Summary

In this blog post I introduced you to the new deployment and rollback system that we have implemented for OpenShift. This has been a top requested feature for both source code and binary deployments and we are happy to provide this functionality to all users, including the free tier, of our platform. We continue to work hard to provide the features that developers are requesting and appreciate all of the feedback that is provided to us.

What's Next?

You write in last paragraph: "If you are Java developer, you may be building your .war or .ear file locally and then pushing that to your OpenShift gear. Good news, we also support binary deployment versioning by changing the deployment type"

How does that actually work ? How do I deploy just the war and ear without shipping the rest of openshift application ?