Running APIcast on Red Hat OpenShift

SaaS On-premises 2.0
This tutorial describes how to use APIcast v2 – the dockerized 3scale API Gateway that is packaged for easy installation and operation on Red Hat OpenShift v3.


To follow the tutorial steps below, you will first need to configure APIcast in your 3scale Admin Portal as per the APIcast Overview. Make sure Self-managed Gateway is selected as the deployment option in the integration settings. You should have both Staging and Production environment configured to proceed.

Step 1: Set up OpenShift

If you already have a running OpenShift cluster, you can skip this step. Otherwise, continue reading.

For production deployments you can follow the instructions for OpenShift installation. In order to get started quickly in development environments, there are a couple of ways you can install OpenShift:

In this tutorial the OpenShift cluster will be installed using:

  • Red Hat Enterprise Linux (RHEL) 7
  • Docker v1.10.3
  • OpenShift Origin command line interface (CLI) - v1.3.1

Install Docker

Docker packages provided by Red Hat are released as part of the Extras channel in RHEL. To enable additional repositories, you can use either the Subscription Manager, or Yum config manager, see the RHEL product documentation for details.

For a RHEL 7 deployed on a AWS EC2 instance we'll use the following the instructions:

1. List all repositories:

sudo yum repolist all

Find the *-extras repository.

2. Enable extras repository:

sudo yum-config-manager --enable rhui-REGION-rhel-server-extras

3. Install Docker packages:

sudo yum install docker docker-registry

4. Add an insecure registry of by adding or uncommenting the following line in /etc/sysconfig/docker file:


5. Start Docker:

sudo systemctl start docker

You can verify that Docker is running with the command:

sudo systemctl status docker

Start OpenShift cluster

Download the latest stable release of the client tools (openshift-origin-client-tools-VERSION-linux-64bit.tar.gz) from OpenShift releases page, and place the Linux oc binary extracted from the archive in your PATH.

Note: Please be aware that the oc cluster set of commands are only available in the 1.3+ or newer releases.

Note: Docker daemon runs as the root user, so you will need to run any oc or Docker commands with root privileges.

Open a terminal with a user that has permission to run Docker commands and run:

oc cluster up

At the bottom of the output you will find information about the deployed cluster:

-- Server Information ...
  OpenShift server started.
  The server is accessible via web console at:

  You are logged in as:
    User:     developer
    Password: developer

  To login as administrator:
    oc login -u system:admin

Note the IP address that is assigned to your OpenShift server, we will refer to it in the tutorial as OPENSHIFT-SERVER-IP.

Setting up OpenShift cluster on a remote server

In case you are deploying the OpenShift cluster on a remote server, you will need to explicitly specify a public hostname and a routing suffix on starting the cluster, in order to be able to access the OpenShift web console remotely.

For example, if you are deploying on an AWS EC2 instance, you should specify the following options:

oc cluster up

where is the Public Domain, and 54.321.67.89 is the IP of the instance. You will then be able to access the OpenShift web console at

Step 2: Deploy APIcast using the OpenShift template

1. By default you are logged in as developer and can proceed to the next step.

Otherwise login into OpenShift using the oc login command from the OpenShift Client tools you downloaded and installed in the previous step. The default login credentials are username = "developer" and password = "developer":

oc login https://OPENSHIFT-SERVER-IP:8443

You should see Login successful. in the output.

2. Create your project. This example sets the display name as gateway

oc new-project "3scalegateway" --display-name="gateway" --description="3scale gateway demo"

The response should look like this:

Now using project "3scalegateway" on server "".

Ignore the suggested next steps in the text output at the command prompt and proceed to the next step below.

3. Create a new Secret to reference your project by replacing and with yours.

oc secret new-basicauth apicast-configuration-url-secret --password=https://<ACCESS_TOKEN>@<DOMAIN>

Here <ACCESS_TOKEN> is an Access Token (not a Service Token) for the 3scale Account Management API, and <DOMAIN> is the URL of your 3scale Admin Portal.

The response should look like this:


4. Create an application for your APIcast Gateway from the template, and start the deployment:

oc new-app -f

You should see the following messages at the bottom of the output:

--> Creating resources with label app=3scale-gateway ...
    deploymentconfig "apicast" created
    service "apicast" created
--> Success
    Run 'oc status' to view your app.

Step 3: Create routes in OpenShift console

1. Open the web console for your OpenShift cluster in your browser: https://OPENSHIFT-SERVER-IP:8443/console/

Use the value specified in --public-hostname instead of OPENSHIFT-SERVER-IP if you started OpenShift cluster on a remote server.

You should see the login screen:

OpenShift Login Screen
Note: You may receive a warning about an untrusted web-site. This is expected, as we are trying to access the web console through secure protocol, without having configured a valid certificate. While you should avoid this in production environment, for this test setup you can go ahead and create an exception for this address.

2. Log in using the developer credentials created or obtained in the Setup OpenShift section above.

You will see a list of projects, including the "gateway" project you created from the command line above.

Openshift Projects

If you do not see your gateway project, you probably created it with a different user and will need to assign the policy role to to this user.

3. Click on "gateway" and you will see the Overview tab.

OpenShift downloaded the code for APIcast and started the deployment. You may see the message Deployment #1 running when the deployment is in progress.

When the build completes, the UI will refresh and show two instances of APIcast ( 2 pods ) that have been started by OpenShift, as defined in the template.

Building the Gateway

Each APIcast instance, upon starting, downloads the required configuration from 3scale using the settings you provided on the Integration page of your 3scale Admin Portal.

OpenShift will maintain two APIcast instances and monitor the health of both; any unhealthy APIcast instance will automatically be replaced with a new one.

4. In order to allow your APIcast instances to receive traffic, you'll need to create a route. Start by clicking on Create Route.

Create Route

Enter the same host you set in 3scale above in the section Public Base URL (without the http:// and without the port) , e.g. gateway.openshift.demo, then click the Create button.

Configure Route

Create a new route for every 3scale service you define. Alternatively, you could avoid having to create a new route for every 3scale service you define by deploying a wildcard router.

Configure wildcard domains (technical preview)

Technical preview: Note that the wildcard router is currently a technical preview feature.


Use of the wildcard domain feature requires the following:

  • OpenShift version 3.4
  • a wildcard domain that is not being used for any other routes, or as another project’s namespace domain
  • your router must be configured to allow wildcard routes


Perform the following steps to configure a wildcard domain:

  1. From a terminal session, log in to OpenShift: oc login
  2. Create a wildcard router configured with your wildcard domain
  3. Download the wildcard.yml template from the latest release in this GitHub repository.
  4. Switch to the project which contains your AMP deployment: oc project <project_name>
  5. Enter the oc new-app command, specifying the following:
  • the -file option and the path to the wildcard.yml template
  • the --param option and the WILDCARD_DOMAIN of your openshift cluster
  • the --param option and the TENANT_NAME from the project which contains your AMP deployment

oc new-app -f wildcard.yml --param WILDCARD_DOMAIN=<> --param TENANT_NAME=<organization-name>

Once configured, your AMP deployment will connect to the built-in APIcast gateways automatically and direct all subdomain traffic through your wildcard domain.


Consider the following limitations when using the wildcard domain feature: - API endpoints must end with the -staging or -production suffix (e.g. api1-,, If your API endpoints do not have one of these suffixes, calls will return a 500 error code. - You must deploy the router in same project as the AMP - This template will work only with an AMP.yml deployment

More information

For more information about wildcard domains on OpenShift, visit Using Wildcard Routes (for a Subdomain)

Your API Gateways are now ready to receive traffic. OpenShift takes care of load-balancing incoming requests to the route across the two running APIcast instances.

If you wish to see the APIcast logs, you can do so by clicking Applications > Pods, selecting one of the pods and finally selecting Logs.

Step 4: Test APIcast

1. Test that APIcast authorizes a valid call to your API, by executing a curl command with your valid user_key to the hostname that you configured in the previous step, e.g. :

curl "http://gateway.openshift.demo/?user_key=YOUR_USER_KEY"

In case you are running the OpenShift cluster locally, you will need to add the hostname gateway.openshift.demo for your OPENSHIFT-SERVER-IP to the /etc/hosts file, for example: gateway.openshift.demo

Alternatively, you can specify the hostname of the gateway in the Host header when making the request:

curl "http://OPENSHIFT-SERVER-IP/?user_key=YOUR_USER_KEY" -H "Host: gateway.openshift.demo"

This last option will also work in case your OpenShift cluster is deployed on a remote server. Just use the public IP of the machine where OpenShift is deployed, and specify the hostname from the Public Base URL in the Host header.

This way OpenShift and APIcast will route the request correctly.

2. Test that APIcast does not authorize an invalid call to your API.

curl "http://gateway.openshift.demo/?user_key=INVALID_KEY"

Step 5: Applying changes to APIcast

Of course, your API configuration is not static, in future you may wish to apply changes to it, for example, choose another authentication method, add new methods and metrics, update the mapping rules, or make any other change on the Integration page for your API. In this case you will need to redeploy the APIcast gateway to make the changes effective. In order to do this, on your Openshift instance, go to Applications > Deployments > threescalegw and click on Deploy.

Deploy OpenShift API Gateway

New pods will be created using the updated configuration, and the old ones will be retired. OpenShift supports different deployment strategies, you can learn more about them in the OpenShift documentation

Multiple services

If you have multiple services (APIs) in 3scale, you will need to configure the routing properly:

1. For each API, go to the Integration tab, and in Production section enter the Public Base URL and click on Update Production Configuration to save the changes. Make sure you use a different Public Base URL for each API, for example, http://search-api.openshift.demo for the service called Search API and http://video-api.openshift.demo for Video API.

2. In OpenShift create routes for the gateway service ("threescalegw"): http://search-api.openshift.demo and http://video-api.openshift.demo. From Applications > Routes you can create a new route or modify and existing one. Note that you can't change the hostname for already created routes, but you can delete an existing route and add a new one.

Create routes for multiple services

3. You will need to redeploy the gateway to apply the changes you've made in the 3scale admin portal. Go to Applications > Deployments > threescalegw and click on Deploy.

4. Now you can make calls to both APIs, and they will be routed to either Search API or Video API depending on the hostname. For example:

curl "http://search-api.openshift.demo/find?query=openshift&user_key=YOUR_USER_KEY"
curl "http://video-api.openshift.demo/categories?user_key=YOUR_USER_KEY"

In case you are running the OpenShift cluster locally, in order for the above calls to work properly you will need to add the hostnames for your OPENSHIFT-SERVER-IP to the /etc/hosts file: search-api.openshift.demo video-api.openshift.demo

In case your OpenShift cluster is hosted remotely, you can specify the host configured in Public Base URL in the Host header in order to get it routed corectly by OpenShift and the API gateway:

curl "http://YOUR-PUBLIC-IP/find?query=openshift&user_key=YOUR_USER_KEY" -H "Host: search-api.openshift.demo"
curl "http://YOUR-PUBLIC-IP/categories?user_key=YOUR_USER_KEY" -H "Host: video-api.openshift.demo"

Changing APIcast parameters

APIcast v2 has a number of parameters that can enable/disable different features or change its behavior. These parameters are defined in the OpenShift template. You can find the complete list in the template YAML file. The template parameters are mapped to environment variables that will be set for each running pod.

You can specify the values for the parameters when creating a new application with oc new-app command using the -p | --param argument, for example:

oc new-app -f -p APICAST_LOG_LEVEL=debug

In order to change the parameters for an existing application, you can modify the environment variables values. Go to Applications > Deployments > threescalegw and select the Environment tab.

OpenShift environment

After modifying the values, click on Save button at the bottom, and then Deploy to apply the changes in the running API Gateway.


Your API is now protected by two APIcast instances running on Red Hat OpenShift.

Next Steps

Now that you have an API Gateway up and running on your local machine you can:

  1. Explore how to configure access policies for your API, and engage developers with a Developer Portal by following the Quickstart guide.
  2. Run OpenShift V3 on your dedicated datacenter or on your favorite cloud platform using the advanced installation documentation listed above.
  3. Register a custom domain name for your API services, and configure your API integration in 3scale Admin Portal, and in OpenShift by adding new routes.
  4. Learn more about OpenShift from the OpenShift documentation