Red Hat Training

A Red Hat training course is available for OpenShift Container Platform

Chapter 6. Migrating Applications

6.1. Overview

This topic covers the migration procedure of OpenShift version 2 (v2) applications to OpenShift version 3 (v3).

Note

This topic uses some terminology that is specific to OpenShift v2. Comparing OpenShift Enterprise 2 and OpenShift Enterprise 3 provides insight on the differences between the two versions and the language used.

To migrate OpenShift v2 applications to OpenShift Container Platform v3, all cartridges in the v2 application must be recorded as each v2 cartridge is equivalent with a corresponding image or template in OpenShift Container Platform v3 and they must be migrated individually. For each cartridge, all dependencies or required packages also must be recorded, as they must be included in the v3 images.

The general migration procedure is:

  1. Back up the v2 application.

    • Web cartridge: The source code can be backed up to a Git repository such as by pushing to a repository on GitHub.
    • Database cartridge: The database can be backed up using a dump command (mongodump, mysqldump, pg_dump) to back up the database.
    • Web and database cartridges: rhc client tool provides snapshot ability to back up multiple cartridges:

      $ rhc snapshot save <app_name>

      The snapshot is a tar file that can be unzipped, and its content is application source code and the database dump.

  2. If the application has a database cartridge, create a v3 database application, sync the database dump to the pod of the new v3 database application, then restore the v2 database in the v3 database application with database restore commands.
  3. For a web framework application, edit the application source code to make it v3 compatible. Then, add any dependencies or packages required in appropriate files in the Git repository. Convert v2 environment variables to corresponding v3 environment variables.
  4. Create a v3 application from source (your Git repository) or from a quickstart with your Git URL. Also, add the database service parameters to the new application to link the database application to the web application.
  5. In v2, there is an integrated Git environment and your applications automatically rebuild and restart whenever a change is pushed to your v2 Git repository. In v3, in order to have a build automatically triggered by source code changes pushed to your public Git repository, you must set up a webhook after the initial build in v3 is completed.

6.2. Migrating Database Applications

6.2.1. Overview

This topic reviews how to migrate MySQL, PostgreSQL, and MongoDB database applications from OpenShift version 2 (v2) to OpenShift version 3 (v3).

6.2.2. Supported Databases

v2v3

MongoDB: 2.4

MongoDB: 2.4, 2.6

MySQL: 5.5

MySQL: 5.5, 5.6

PostgreSQL: 9.2

PostgreSQL: 9.2, 9.4

6.2.3. MySQL

  1. Export all databases to a dump file and copy it to a local machine (into the current directory):

    $ rhc ssh <v2_application_name>
    $ mysqldump --skip-lock-tables -h $OPENSHIFT_MYSQL_DB_HOST -P ${OPENSHIFT_MYSQL_DB_PORT:-3306} -u ${OPENSHIFT_MYSQL_DB_USERNAME:-'admin'} \
     --password="$OPENSHIFT_MYSQL_DB_PASSWORD" --all-databases > ~/app-root/data/all.sql
    $ exit
  2. Download dbdump to your local machine:

    $ mkdir mysqldumpdir
    $ rhc scp -a <v2_application_name> download mysqldumpdir app-root/data/all.sql
  3. Create a v3 mysql-persistent pod from template:

    $ oc new-app mysql-persistent -p \
       MYSQL_USER=<your_V2_mysql_username> -p \
       MYSQL_PASSWORD=<your_v2_mysql_password> -p MYSQL_DATABASE=<your_v2_database_name>
  4. Check to see if the pod is ready to use:

    $ oc get pods
  5. When the pod is up and running, copy database archive files to your v3 MySQL pod:

    $ oc rsync /local/mysqldumpdir <mysql_pod_name>:/var/lib/mysql/data
  6. Restore the database in the v3 running pod:

    $ oc rsh <mysql_pod>
    $ cd /var/lib/mysql/data/mysqldumpdir

    In v3, to restore databases you need to access MySQL as root user.

    In v2, the $OPENSHIFT_MYSQL_DB_USERNAME had full privileges on all databases. In v3, you must grant privileges to $MYSQL_USER for each database.

    $ mysql -u root
    $ source all.sql

    Grant all privileges on <dbname> to <your_v2_username>@localhost, then flush privileges.

  7. Remove the dump directory from the pod:

    $ cd ../; rm -rf /var/lib/mysql/data/mysqldumpdir

Supported MySQL Environment Variables

v2v3

OPENSHIFT_MYSQL_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_MYSQL_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_MYSQL_DB_USERNAME

MYSQL_USER

OPENSHIFT_MYSQL_DB_PASSWORD

MYSQL_PASSWORD

OPENSHIFT_MYSQL_DB_URL

 

OPENSHIFT_MYSQL_DB_LOG_DIR

 

OPENSHIFT_MYSQL_VERSION

 

OPENSHIFT_MYSQL_DIR

 

OPENSHIFT_MYSQL_DB_SOCKET

 

OPENSHIFT_MYSQL_IDENT

 

OPENSHIFT_MYSQL_AIO

MYSQL_AIO

OPENSHIFT_MYSQL_MAX_ALLOWED_PACKET

MYSQL_MAX_ALLOWED_PACKET

OPENSHIFT_MYSQL_TABLE_OPEN_CACHE

MYSQL_TABLE_OPEN_CACHE

OPENSHIFT_MYSQL_SORT_BUFFER_SIZE

MYSQL_SORT_BUFFER_SIZE

OPENSHIFT_MYSQL_LOWER_CASE_TABLE_NAMES

MYSQL_LOWER_CASE_TABLE_NAMES

OPENSHIFT_MYSQL_MAX_CONNECTIONS

MYSQL_MAX_CONNECTIONS

OPENSHIFT_MYSQL_FT_MIN_WORD_LEN

MYSQL_FT_MIN_WORD_LEN

OPENSHIFT_MYSQL_FT_MAX_WORD_LEN

MYSQL_FT_MAX_WORD_LEN

OPENSHIFT_MYSQL_DEFAULT_STORAGE_ENGINE

 

OPENSHIFT_MYSQL_TIMEZONE

 
 

MYSQL_DATABASE

 

MYSQL_ROOT_PASSWORD

 

MYSQL_MASTER_USER

 

MYSQL_MASTER_PASSWORD

6.2.4. PostgreSQL

  1. Back up the v2 PostgreSQL database from the gear:

    $ rhc ssh -a <v2-application_name>
    $ mkdir ~/app-root/data/tmp
    $ pg_dump <database_name> | gzip > ~/app-root/data/tmp/<database_name>.gz
  2. Extract the backup file back to your local machine:

    $ rhc scp -a <v2_application_name> download <local_dest> app-root/data/tmp/<db-name>.gz
    $ gzip -d <database-name>.gz
    Note

    Save the backup file to a separate folder for step 4.

  3. Create the PostgreSQL service using the v2 application database name, user name and password to create the new service:

    $ oc new-app postgresql-persistent -p POSTGRESQL_DATABASE=dbname -p
    POSTGRESQL_PASSWORD=password -p POSTGRESQL_USER=username
  4. Check to see if the pod is ready to use:

    $ oc get pods
  5. When the pod is up and running, sync the backup directory to pod:

    $ oc rsync /local/path/to/dir <postgresql_pod_name>:/var/lib/pgsql/data
  6. Remotely access the pod:

    $ oc rsh <pod_name>
  7. Restore the database:

    psql dbname < /var/lib/pgsql/data/<database_backup_file>
  8. Remove all backup files that are no longer needed:

    $ rm /var/lib/pgsql/data/<database-backup-file>

Supported PostgreSQL Environment Variables

v2v3

OPENSHIFT_POSTGRESQL_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_POSTGRESQL_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_POSTGRESQL_DB_USERNAME

POSTGRESQL_USER

OPENSHIFT_POSTGRESQL_DB_PASSWORD

POSTGRESQL_PASSWORD

OPENSHIFT_POSTGRESQL_DB_LOG_DIR

 

OPENSHIFT_POSTGRESQL_DB_PID

 

OPENSHIFT_POSTGRESQL_DB_SOCKET_DIR

 

OPENSHIFT_POSTGRESQL_DB_URL

 

OPENSHIFT_POSTGRESQL_VERSION

 

OPENSHIFT_POSTGRESQL_SHARED_BUFFERS

 

OPENSHIFT_POSTGRESQL_MAX_CONNECTIONS

 

OPENSHIFT_POSTGRESQL_MAX_PREPARED_TRANSACTIONS

 

OPENSHIFT_POSTGRESQL_DATESTYLE

 

OPENSHIFT_POSTGRESQL_LOCALE

 

OPENSHIFT_POSTGRESQL_CONFIG

 

OPENSHIFT_POSTGRESQL_SSL_ENABLED

 
 

POSTGRESQL_DATABASE

 

POSTGRESQL_ADMIN_PASSWORD

6.2.5. MongoDB

Note
  • For OpenShift v3: MongoDB shell version 3.2.6
  • For OpenShift v2: MongoDB shell version 2.4.9
  1. Remotely access the v2 application via the ssh command:

    $ rhc ssh <v2_application_name>
  2. Run mongodump, specifying a single database with -d <database_name> -c <collections>. Without those options, dump all databases. Each database is dumped in its own directory:

    $ mongodump -h $OPENSHIFT_MONGODB_DB_HOST -o app-root/repo/mydbdump -u 'admin' -p $OPENSHIFT_MONGODB_DB_PASSWORD
    $ cd app-root/repo/mydbdump/<database_name>; tar -cvzf dbname.tar.gz
    $ exit
  3. Download dbdump to a local machine in the mongodump directory:

    $ mkdir mongodump
    $ rhc scp -a <v2 appname> download mongodump \
      app-root/repo/mydbdump/<dbname>/dbname.tar.gz
  4. Start a MongoDB pod in v3. Because the latest image (3.2.6) does not include mongo-tools, to use mongorestore or mongoimport commands you need to edit the default mongodb-persistent template to specify the image tag that contains the mongo-tools, “mongodb:2.4”. For that reason, the following oc get --export command and edit are necessary:

    $ oc get -o json --export template mongodb-persistent -n openshift > mongodb-24persistent.json

    Edit L80 of mongodb-24persistent.json; replace mongodb:latest with mongodb:2.4.

    $ oc new-app --template=mongodb-persistent -n <project-name-that-template-was-created-in> \
      MONGODB_USER=user_from_v2_app -p \
      MONGODB_PASSWORD=password_from_v2_db -p \
      MONGODB_DATABASE=v2_dbname -p \
      MONGODB_ADMIN_PASSWORD=password_from_v2_db
    $ oc get pods
  5. When the mongodb pod is up and running, copy the database archive files to the v3 MongoDB pod:

    $ oc rsync local/path/to/mongodump <mongodb_pod_name>:/var/lib/mongodb/data
    $ oc rsh <mongodb_pod>
  6. In the MongoDB pod, complete the following for each database you want to restore:

    $ cd /var/lib/mongodb/data/mongodump
    $ tar -xzvf dbname.tar.gz
    $ mongorestore -u $MONGODB_USER -p $MONGODB_PASSWORD -d dbname -v /var/lib/mongodb/data/mongodump
  7. Check if the database is restored:

    $ mongo admin -u $MONGODB_USER -p $MONGODB_ADMIN_PASSWORD
    $ use dbname
    $ show collections
    $ exit
  8. Remove the mongodump directory from the pod:

    $ rm -rf /var/lib/mongodb/data/mongodump

Supported MongoDB Environment Variables

v2v3

OPENSHIFT_MONGODB_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_MONGODB_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_MONGODB_DB_USERNAME

MONGODB_USER

OPENSHIFT_MONGODB_DB_PASSWORD

MONGODB_PASSWORD

OPENSHIFT_MONGODB_DB_URL

 

OPENSHIFT_MONGODB_DB_LOG_DIR

 
 

MONGODB_DATABASE

 

MONGODB_ADMIN_PASSWORD

 

MONGODB_NOPREALLOC

 

MONGODB_SMALLFILES

 

MONGODB_QUIET

 

MONGODB_REPLICA_NAME

 

MONGODB_KEYFILE_VALUE

6.3. Migrating Web Framework Applications

6.3.1. Overview

This topic reviews how to migrate Python, Ruby, PHP, Perl, Node.js, WordPress, Ghost, JBoss EAP, JBoss WS (Tomcat), and Wildfly 10 (JBoss AS) web framework applications from OpenShift version 2 (v2) to OpenShift version 3 (v3).

6.3.2. Python

  1. Set up a new GitHub repository and add it as a remote branch to the current, local v2 Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>.git
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. Ensure that all important files such as setup.py, wsgi.py, requirements.txt, and etc are pushed to new repository.

    • Ensure all required packages for your application are included in requirements.txt.
  4. Use the oc command to launch a new Python application from the builder image and source code:

    $ oc new-app --strategy=source
    python:3.3~https://github.com/<github-id>/<repo-name> --name=<app-name> -e
    <ENV_VAR_NAME>=<env_var_value>

Supported Python Versions

v2v3

Python: 2.6, 2.7, 3.3

Supported Container Images

Django

Django-psql-example (quickstart)

6.3.3. Ruby

  1. Set up a new GitHub repository and add it as a remote branch to the current, local v2 Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>.git
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. If you do not have a Gemfile and are running a simple rack application, copy this Gemfile into the root of your source:

    https://github.com/sclorg/ruby-ex/blob/master/Gemfile
    Note

    The latest version of the rack gem that supports Ruby 2.0 is 1.6.4, so the Gemfile needs to be modified to gem 'rack', “1.6.4”.

    For Ruby 2.2 or later, use the rack gem 2.0 or later.

  4. Use the oc command to launch a new Ruby application from the builder image and source code:

    $ oc new-app --strategy=source
    ruby:2.0~https://github.com/<github-id>/<repo-name>.git

Supported Ruby Versions

v2v3

Ruby: 1.8, 1.9, 2.0

Supported Container Images

Ruby on Rails: 3, 4

Rails-postgresql-example (quickstart)

Sinatra

 

6.3.4. PHP

  1. Set up a new GitHub repository and add it as a remote branch to the current, local v2 Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. Use the oc command to launch a new PHP application from the builder image and source code:

    $ oc new-app https://github.com/<github-id>/<repo-name>.git
    --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>

Supported PHP Versions

v2v3

PHP: 5.3, 5.4

Supported Container Images

PHP 5.4 with Zend Server 6.1

 

CodeIgniter 2

 

HHVM

 

Laravel 5.0

 
 

cakephp-mysql-example (quickstart)

6.3.5. Perl

  1. Set up a new GitHub repository and add it as a remote branch to the current, local v2 Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. Edit the local Git repository and push changes upstream to make it v3 compatible:

    1. In v2, CPAN modules reside in .openshift/cpan.txt. In v3, the s2i builder looks for a file named cpanfile in the root directory of the source.

      $ cd <local-git-repository>
      $ mv .openshift/cpan.txt cpanfile

      Edit cpanfile, as it has a slightly different format:

      format of cpanfileformat of cpan.txt

      requires ‘cpan::mod’;

      cpan::mod

      requires ‘Dancer’;

      Dancer

      requires ‘YAML’;

      YAML

    2. Remove .openshift directory

      Note

      In v3, action_hooks and cron tasks are not supported in the same way. See Action Hooks for more information.

  4. Use the oc command to launch a new Perl application from the builder image and source code:
$ oc new-app https://github.com/<github-id>/<repo-name>.git

Supported Perl Versions

v2v3

Perl: 5.10

Supported Container Images

 

Dancer-mysql-example (quickstart)

6.3.6. Node.js

  1. Set up a new GitHub repository and add it as a remote branch to the current, local Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. Edit the local Git repository and push changes upstream to make it v3 compatible:

    1. Remove the .openshift directory.

      Note

      In v3, action_hooks and cron tasks are not supported in the same way. See Action Hooks for more information.

    2. Edit server.js.

      • L116 server.js: 'self.app = express();'
      • L25 server.js: self.ipaddress = '0.0.0.0';
      • L26 server.js: self.port = 8080;

        Note

        Lines(L) are from the base V2 cartridge server.js.

  4. Use the oc command to launch a new Node.js application from the builder image and source code:

    $ oc new-app https://github.com/<github-id>/<repo-name>.git
    --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>

Supported Node.js Versions

v2v3

Node.js 0.10

Supported Container Images

 

Nodejs-mongodb-example. This quickstart template only supports Node.js version 6.

6.3.7. WordPress

Important

Currently, support for migrating WordPress applications is offered by the community only and not by Red Hat support.

For guidance on migrating WordPress applications to OpenShift Container Platform v3, see the OpenShift blog.

6.3.8. Ghost

Important

Currently, support for migrating Ghost applications is offered by the community only and not by Red Hat support.

For guidance on migrating Ghost applications to OpenShift Container Platform v3, see the OpenShift blog.

6.3.9. JBoss EAP

  1. Set up a new GitHub repository and add it as a remote branch to the current, local Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. If the repository includes pre-built .war files, they need to reside in the deployments directory off the root directory of the repository.
  4. Create the new application using the JBoss EAP 7 builder image (jboss-eap70-openshift) and the source code repository from GitHub:

    $ oc new-app --strategy=source jboss-eap70-openshift:1.6~https://github.com/<github-id>/<repo-name>.git

6.3.10. JBoss WS (Tomcat)

  1. Set up a new GitHub repository and add it as a remote branch to the current, local Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. If the repository includes pre-built .war files, they need to reside in the deployments directory off the root directory of the repository.
  4. Create the new application using the JBoss Web Server 3 (Tomcat 7) builder image (jboss-webserver30-tomcat7) and the source code repository from GitHub:

    $ oc new-app --strategy=source
    jboss-webserver30-tomcat7-openshift~https://github.com/<github-id>/<repo-name>.git
    --name=<app-name> -e <ENV_VAR_NAME>=<env_var_value>

6.3.11. JBoss AS (Wildfly 10)

  1. Set up a new GitHub repository and add it as a remote branch to the current, local Git repository:

    $ git remote add <remote-name> https://github.com/<github-id>/<repo-name>
  2. Push the local v2 source code to the new repository:

    $ git push -u <remote-name> master
  3. Edit the local Git repository and push the changes upstream to make it v3 compatible:

    1. Remove .openshift directory.

      Note

      In v3, action_hooks and cron tasks are not supported in the same way. See Action Hooks for more information.

    2. Add the deployments directory to the root of the source repository. Move the .war files to ‘deployments’ directory.
  4. Use the oc command to launch a new Wildfly application from the builder image and source code:

    $ oc new-app https://github.com/<github-id>/<repo-name>.git
     --image-stream=”openshift/wildfly:10.0" --name=<app-name> -e
     <ENV_VAR_NAME>=<env_var_value>
    Note

    The argument --name is optional to specify the name of your application. The argument -e is optional to add environment variables that are needed for build and deployment processes, such as OPENSHIFT_PYTHON_DIR.

6.3.12. Supported JBoss Versions

v2v3

JBoss App Server 7

 

Tomcat 6 (JBoss EWS 1.0)

Supported Container Images

Tomcat 7 (JBoss EWS 2.0)

Supported Container Images

Vert.x 2.1

 

WildFly App Server 10

 

WildFly App Server 8.2.1.Final

 

WildFly App Server 9

 

CapeDwarf

 

JBoss Data Virtualization 6

Supported Container Images

JBoss Enterprise App Platform (EAP) 6

Supported Container Images

JBoss Unified Push Server 1.0.0.Beta1, Beta2

 

JBoss BPM Suite

Supported Container Images

JBoss BRMS

Supported Container Images

 

jboss-eap70-openshift: 1.3-Beta

 

eap64-https-s2i

 

eap64-mongodb-persistent-s2i

 

eap64-mysql-persistent-s2i

 

eap64-psql-persistent-s2i

6.4. QuickStart Examples

6.4.1. Overview

Although there is no clear-cut migration path for v2 quickstart to v3 quickstart, the following quickstarts are currently available in v3. If you have an application with a database, rather than using oc new-app to create your application, then oc new-app again to start a separate database service and linking the two with common environment variables, you can use one of the following to instantiate the linked application and database at once, from your GitHub repository containing your source code. You can list all available templates with oc get templates -n openshift:

6.4.2. Workflow

Run a git clone of one of the above template URLs locally. Add and commit your application source code and push a GitHub repository, then start a v3 quickstart application from one of the templates listed above:

  1. Create a GitHub repository for your application.
  2. Clone a quickstart template and add your GitHub repository as a remote:

    $ git clone <one-of-the-template-URLs-listed-above>
    $ cd <your local git repository>
    $ git remote add upstream <https://github.com/<git-id>/<quickstart-repo>.git>
    $ git push -u upstream master
  3. Commit and push your source code to GitHub:

    $ cd <your local repository>
    $ git commit -am “added code for my app”
    $ git push origin master
  4. Create a new application in v3:

    $ oc new-app --template=<template> \
    -p SOURCE_REPOSITORY_URL=<https://github.com/<git-id>/<quickstart_repo>.git> \
    -p DATABASE_USER=<your_db_user> \
    -p DATABASE_NAME=<your_db_name> \
    -p DATABASE_PASSWORD=<your_db_password> \
    -p DATABASE_ADMIN_PASSWORD=<your_db_admin_password> 1
    1
    Only applicable for MongoDB.

    You should now have 2 pods running, a web framework pod, and a database pod. The web framework pod environment should match the database pod environment. You can list the environment variables with oc set env pod/<pod_name> --list:

    • DATABASE_NAME is now <DB_SERVICE>_DATABASE
    • DATABASE_USER is now <DB_SERVICE>_USER
    • DATABASE_PASSWORD is now <DB_SERVICE>_PASSWORD
    • DATABASE_ADMIN_PASSWORD is now MONGODB_ADMIN_PASSWORD (only applicable for MongoDB)

      If no SOURCE_REPOSITORY_URL is specified, the template will use the template URL (https://github.com/openshift/<quickstart>-ex) listed above as the source repository, and a hello-welcome application will be started.

  5. If you are migrating a database, export databases to a dump file and restore the database in the new v3 database pod. Refer to the steps outlined in Database Applications, skipping the oc new-app step as the database pod is already up and running.

6.5. Continuous Integration and Deployment (CI/CD)

6.5.1. Overview

This topic reviews the differences in continuous integration and deployment (CI/CD) applications between OpenShift version 2 (v2) and OpenShift version 3 (v3) and how to migrate these applications into the v3 environment.

6.5.2. Jenkins

The Jenkins applications in OpenShift version 2 (v2) and OpenShift version 3 (v3) are configured differently due to fundamental differences in architecture. For example, in v2, the application uses an integrated Git repository that is hosted in the gear to store the source code. In v3, the source code is located in a public or private Git repository that is hosted outside of the pod.

Furthermore, in OpenShift v3, Jenkins jobs can not only be triggered by source code changes, but also by changes in ImageStream, which are changes on the images that are used to build the application along with its source code. As a result, it is highly recommended that you migrate the Jenkins application manually by creating a new Jenkins application in v3, and then re-creating jobs with the configurations that are suitable to OpenShift v3 environment.

Consult these resources for more information on how to create a Jenkins application, configure jobs, and use Jenkins plug-ins properly:

6.6. Webhooks and Action Hooks

6.6.1. Overview

This topic reviews the differences in webhooks and action hooks between OpenShift version 2 (v2) and OpenShift version 3 (v3) and how to migrate these applications into the v3 environment.

6.6.2. Webhooks

  1. After creating a BuildConfig from a GitHub repository, run:

    $ oc describe bc/<name-of-your-BuildConfig>

    This will output a webhook GitHub URL that looks like:

    <https://api.starter-us-east-1.openshift.com:443/oapi/v1/namespaces/nsname/buildconfigs/bcname/webhooks/secret/github>.
  2. Cut and paste this URL into GitHub, from the GitHub web console.
  3. In your GitHub repository, select Add Webhook from Settings → Webhooks & Services.
  4. Paste the URL output (similar to above) into the Payload URL field.
  5. Set the Content Type to application/json.
  6. Click Add webhook.

You should see a message from GitHub stating that your webhook was successfully configured.

Now, whenever you push a change to your GitHub repository, a new build will automatically start, and upon a successful build a new deployment will start.

Note

If you delete or recreate your application, you will have to update the Payload URL field in GitHub with the new BuildConfig webhook url.

6.6.3. Action Hooks

In OpenShift version 2 (v2), there are build, deploy, post_deploy, and pre_build scripts or action_hooks that are located in the .openshift/action_hooks directory. While there is no one-to-one mapping of function for these in v3, the S2I tool in v3 does have the option of adding customizable scripts, either in a designated URL or in the .s2i/bin directory of your source repository.

OpenShift version 3 (v3) also offers a post-build hook for running basic testing of an image after it is built and before it is pushed to the registry. Deployment hooks are configured in the deployment configuration.

In v2, action_hooks are commonly used to set up environment variables. In v2, any environment variables should be passed with:

$ oc new-app <source-url> -e ENV_VAR=env_var

or:

$ oc new-app <template-name> -p ENV_VAR=env_var

Also, environment variables can be added or changed using:

$ oc set env dc/<name-of-dc>
ENV_VAR1=env_var1 ENV_VAR2=env_var2’

6.7. S2I Tool

6.7.1. Overview

The Source-to-Image (S2I) tool injects application source code into a container image and the final product is a new and ready-to-run container image that incorporates the builder image and built source code. The S2I tool can be installed on your local machine without OpenShift Container Platform from the repository.

The S2I tool is a very powerful tool to test and verify your application and images locally before using them on OpenShift Container Platform.

6.7.2. Creating a Container Image

  1. Identify the builder image that is needed for the application. Red Hat offers multiple builder images for different languages including Python, Ruby, Perl, PHP, and Node.js. Other images are available from the community space.
  2. S2I can build images from source code in a local file system or from a Git repository. To build a new container image from the builder image and the source code:

    $ s2i build <source-location> <builder-image-name> <output-image-name>
    Note

    <source-location> can either be a Git repository URL or a directory to source code in a local file system.

  3. Test the built image with the Docker daemon:

    $ docker run -d --name <new-name> -p <port-number>:<port-number> <output-image-name>
    $ curl localhost:<port-number>
  4. Push the new image to the OpenShift registry.
  5. Create a new application from the image in the OpenShift registry using the oc command:

    $ oc new-app <image-name>

6.8. Support Guide

6.8.1. Overview

This topic reviews supported languages, frameworks, databases, and markers for OpenShift version 2 (v2) and OpenShift version 3 (v3).

See OpenShift Container Platform tested integrations for more information about common combinations that OpenShift Container Platform customers are using.

6.8.2. Supported Databases

See the Supported Databases section of the Database Applications topic.

6.8.3. Supported Languages

6.8.4. Supported Frameworks

Table 6.1. Supported Frameworks

v2v3

Jenkins Server

jenkins-persistent

Drupal 7

 

Ghost 0.7.5

 

WordPress 4

 

Ceylon

 

Go

 

MEAN

 

6.8.5. Supported Markers

Table 6.2. Python

v2v3

pip_install

If your repository contains requirements.txt, then pip is invoked by default. Otherwise, pip is not used.

Table 6.3. Ruby

v2v3

disable_asset_compilation

This can be done by setting DISABLE_ASSET_COMPILATION environment variable to true on the buildconfig strategy definition.

Table 6.4. Perl

v2v3

enable_cpan_tests

This can be done by setting ENABLE_CPAN_TEST environment variable to true on the build configuration.

Table 6.5. PHP

v2v3

use_composer

composer is always used if the source repository includes a composer.json in the root directory.

Table 6.6. Node.js

v2v3

NODEJS_VERSION

N/A

use_npm

npm is always used to start the application, unless DEV_MODE is set to true, in which case nodemon is used instead.

Table 6.7. JBoss EAP, JBoss WS, WildFly

v2v3

enable_debugging

This option is controlled via the ENABLE_JPDA environment variable set on the deployment configuration by setting it to any non-empty value.

skip_maven_build

If pom.xml is present, maven will be run.

java7

N/A

java8

JavaEE is using JDK8.

Table 6.8. Jenkins

v2v3

enable_debugging

N/A

Table 6.9. All

v2v3

force_clean_build

There is a similar concept in v3, as noCache field in buildconfig forces the container build to rerun each layer. In the S2I build, the incremental flag is false by default, which indicates a clean build.

hot_deploy

Ruby, Python, Perl, PHP, Node.js

enable_public_server_status

N/A

disable_auto_scaling

Autoscaling is off by default and it can be turn on via pod auto-scaling.

6.8.6. Supported Environment Variables