Please note that these documents apply to OpenShift Online v2 only (accounts created before August 1st, 2016).
If you are using one of the OpenShift 3 products, please refer to documents available at docs.openshift.com.

External Services

OpenShift makes it easy to connect external services to your applications. External services can provide a wide range of extra functionality and capabilities for your applications, and are generally categorized into two areas: application services and devops services. For application services, common uses include data persistence, search, caching, messaging, and more. For devops, services provide software lifecycle capabilities such as continuous integration and load testing.

Using External Services

When working with an external resource, we recommend that you use environment variables to model the external service as a native OpenShift add-on cartridge. That way your application can connect with the external service the same way as any other internal service.

Below, we outline a framework for connecting external services to your application along with examples for our trusted partner providers.

Step 1 - Subscribe to an External Service

To get started, subscribe to an external service by visiting the provider’s website and signing up for the service. See the list of recommended external services from our trusted partners below.

Sign up for SendGrid

Step 2 - Locate Your Credentials for Connecting to the Service

Next, locate your API credentials in the service provider’s web console. You may need to create a new set of access keys/tokens.

SendGrid API credentials
Not all external services require direct integration with your application. Some services, like those intended for load testing, can simply interact with your web application via HTTP.

Step 3 - Setting Environment Variables

Next, details about the external service (account credentials, hostnames, ports, etc.) should be written to environment variables available in the application runtime. Your application can use this information to integrate with the external service.

Since our goal is to model the functionality of OpenShift’s native add-on cartridges, we recommend that you prefix your environment variables with the name of the service. For example, for a service named service we would prefix the variables with SERVICE_* as follows:

Variable Name

Example Value

SERVICE_USERNAME

YOUR_USERNAME

SERVICE_PASSWORD

YOUR_PASSWORD

Use the OpenShift client tools to set environment variables to make your credentials available within your application runtime:

$ rhc env set SERVICE_USERNAME=YOUR_USERNAME SERVICE_PASSWORD=YOUR_PASSWORD -a App_Name

You can list the environment variables available to your application to confirm that they were set properly:

$ rhc env list -a App_Name
SERVICE_PASSWORD=YOUR_PASSWORD
SERVICE_USERNAME=YOUR_USERNAME

See using custom environment variables for more details.

Step 4 - Configure Your Application to use Environment Variables

Finally, configure your application to make use of the environment variables.

Code Examples

For the following examples we assume the following environment variables, prefixed with SERVICE_*, have been set:

Variable Name

Example Value

SERVICE_USERNAME

YOUR_USERNAME

SERVICE_PASSWORD

YOUR_PASSWORD

The following code examples show how to access these environment variables within your application.

Java

Using environment variables within your application:

public class Example {
  public static void main(String[] args) {
    System.getenv('SERVICE_USERNAME'); // "YOUR_USERNAME"
    System.getenv('SERVICE_PASSWORD'); // "YOUR_PASSWORD"
  }
}
Node.js

Using environment variables within your application:

process.env.SERVICE_USERNAME; // "YOUR_USERNAME"
accountInfo.SERVICE_PASSWORD; // "YOUR_PASSWORD"
Perl

Using environment variables within your application:

$ENV{'SERVICE_USERNAME'}; # "YOUR_USERNAME"
$ENV{'SERVICE_PASSWORD'}; # "YOUR_PASSWORD"
PHP

Using environment variables within your application:

getenv('SERVICE_USERNAME'); // "YOUR_USERNAME"
getenv('SERVICE_PASSWORD'); // "YOUR_PASSWORD"
Python

Using environment variables within your application:

import os

os.getenv('SERVICE_USERNAME') # "YOUR_USERNAME"
os.getenv('SERVICE_PASSWORD') # "YOUR_PASSWORD"
Ruby

Using environment variables within your application:

ENV['SERVICE_USERNAME'] # "YOUR_USERNAME"
ENV['SERVICE_PASSWORD'] # "YOUR_PASSWORD"

Recommended External Services

The table below provides a list of external services from our trusted partners along with the recommended environment variable prefix. Click on the name of the external service provider in the table below for more information on integrating with the specified provider.

Name Requires Direct Integration Environment Variable

3scale

No

-

BlazeMeter

No

-

cine.io

Yes

CINE_IO_*

ClearDB MySQL Database

Yes

CLEARDB_*

CloudAMQP

Yes

CLOUDAMQP_*

CloudForge

No

-

DreamFactory

No

-

ElephantSQL

Yes

ELEPHANTSQL_*

IronMQ

Yes

IRONMQ_*

IronWorker

Yes

IRONWORKER_*

Load Impact

No

-

Memcached Cloud

Yes

MEMCACHEDCLOUD_*

MemCachier

Yes

MEMCACHIER_*

MongoLab

Yes

MONGOLAB_*

PubNub

No

-

Redis Cloud

Yes

REDISCLOUD_*

Searchly

Yes

SEARCHLY_*

SendGrid

Yes

SENDGRID_*

Statica

Yes

STATICA_*