TUTORIAL:

DEPLOYING A 3SCALE API

GATEWAY ON RED HAT
OPENSHIFT

This tutorial describes how to deploy a dockerized version of the 3scale API
Gateway 1.0 (APIcast) that is packaged for easy installation and operation on
OpenShift V3.

In the tutorial we use the OpenShift Origin VM—a Virtual Machine image
you can download and run locally, so that you can follow this tutorial without
running a full OpenShift deployment.

3scale offers multiple options for implementing traffic management

• Deploy an API gateway, which is a customized reverse proxy between the client
application and your API backend. The gateway then handles authorization of incoming
calls and traffic reporting
• Integrate using a software plugin embedded in your API application code. Native-
language plugins manage request authorization via 3scale’s Service Management API.
Tutorial Prerequisites
To follow the tutorial steps below, you’ll first need to address the following prerequisites:

3scale Account Configuration

You should have a 3scale API provider account (you can easily create one here) and have an API
configured in the 3scale Admin Portal.

These steps will show you how to find the following necessary information:

• Your 3scale admin URL

• The API provider key for your 3scale account
• Your user key

If you already have this information handy and your API is already configured in 3scale, feel free to
skip to the Set up OpenShift section.

If you do not have an API running and configured in your 3scale account, please follow the
instructions in our Quickstart to do so.

Log in to your 3scale Admin Portal with the URL provided to you. It will look something like this:
https://MYDOMAIN-admin.3scale.net/

Note down your 3scale Admin Portal URL, in this tutorial we will refer to it as
THREESCALE_ADMIN_URL
From the Overview sub-tab note down your 3scale Provider Key, referred to in the UI as API Key.

Later in this tutorial we refer to this as your THREESCALE_PROVIDER_KEY

Keep your 3scale Provider Key private. Do not share it with anyone and do not put
into code repositories or into any document that may reveal it to others.

In the 3scale Admin Portal you should either have an API of your own running and configured or
use the Echo API that was set up by the onboarding wizard. This tutorial will use the Echo API as an
example throughout.

Navigate to the Dashboard > API tab. If you have more than one API in your account, select the
API you want to manage with the API gateway. Select the Integration link at top-left.

If you’re setting this up for the first time, you’ll need to test to confirm that your private
(unmanaged) API is working before proceeding. If you’ve already configured your API and sent test
traffic, feel free to skip this step.

In the screenshot above, the 3scale provided Echo API is used as an example. You can use this or
configure the API to refer to your real API’s Private Base URL

Test your private (unmanaged) API is working using this curl command:

curl "https://echo-api.3scale.net:443/"

You should get a response similar to this:

{
"method": "GET",
"path": "/",
"args": "",
"body": "",
"headers": {
"HTTP_VERSION": "HTTP/1.1",
"HTTP_HOST": "echo-api.3scale.net",
"HTTP_USER_AGENT": "curl/7.43.0",
"HTTP_ACCEPT": "*/*",
"HTTP_X_FORWARDED_FOR": "10.1.0.154",
"HTTP_CONNECTION": "close"
}
Once you’ve confirmed that your API is working, scroll down to the bottom of the Staging section
where you can see a sample curl command:

curl "https://XXXXXX.staging.apicast.io:443/?user_key=[MY_USER_KEY]"

Note down your MY_USER_KEY to use later to authenticate to your managed API

Set up OpenShift
1. Download required tools and files
a. Go to https://www.openshift.org/vm/ and click on the Downloads menu item
b. Download and install the required tools vagrant and VirtualBox
c. Download and install the OpenShift Client tools for your operating system and
check they can be executed by typing oc version at a terminal prompt.

2. Start the OpenShift Origin VM

a. Start a command prompt, create a new directory and change into it.
b. At the terminal prompt type:
vagrant init thesteve0/openshift-origin
 That will create a file called Vagrantfile in the current directory.
c. Start the VM using the command vagrant up. Downloading the image and starting
the VM may take several minutes (it may take a bit longer if you’re running
Windows).
Upon starting the VM, you’ll see output which includes instructions for logging in to your
OpenShift Origin VM. :
oc login https://[OPENSHIFT-VM-IP]:8443

Your OPENSHIFT-VM-IP will be unique.

Note down your OPENSHIFT-VM-IP as you’ll need to use it repeatedly in this tutorial.

3. Configure a host for the OpenShift Origin VM on your local machine. This will later
allow you to expose the managed API using a hostname (this tutorial uses the example
gateway.openshift.demo).

You’ll need to add an entry for the Origin VM to your local hosts file.
If your host PC is linux-based, this file is /etc/hosts.
If you are running Windows PC, this hosts file will typically be: C:\Windows\System32\
drivers\etc\hosts

Add a new line like this:

OPENSHIFT-VM-IP gateway.openshift.demo

Example:
10.2.2.2 gateway.openshift.demo

Tutorial Steps
Create your 3scale API Gateway using a template
1. Login into OpenShift using the oc command from the OpenShift Client tools you
downloaded and installed in step 1. The default login credentials are username: admin
and password: admin

oc login https://OPENSHIFT-VM-IP:8443

You may get a security warning and asked whether you wish to continue with an insecure
selection. Choose yes to proceed.

The response should indicate Login successful.

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 "https://[OPENSHIFT-VM-IP]:8443".

3. Create an application template for your 3scale API Gateway.

oc create -f https://raw.githubusercontent.com/3scale/docker-gateway/

master/3scale-gateway-openshift-template.yml -n openshift

The response should look like this:

template "3scale-gateway" created

You may receive an error warning that the template already exists if you’ve previously
attempted this step. You can continue, or login to the UI as described below and delete
any projects from previous attempts and then return to this point.

Deploying the 3scale API Gateway

1. 1. Open the web console for your OpenShift Origin VM in your browser: https://
[OPENSHIFT-VM-IP]:8443/console/

You may receive a warning about an untrusted web-site. As this is the Origin VM running
on your local machine there are no real risks. Select Accept the Risks in the browser and
proceed to view the Web console.

You should see the login screen:

2. Login using the default credentials of u: admin and p: admin

Your list of projects will now include the gateway project you created from the command
line above.

3. Select the gateway project and then click the Add to Project button.
4. Search for 3scale and select the 3scale-gateway template.
5. You’ll be prompted to add your 3scale account details at this step. You’ll need to include:
THREESCALE_ADMIN_URL (including "https://") and THREESCALE_PROVIDER_KEY

When you’ve added this information, scroll to the bottom of the page and click Create

6. You will be shown the Application created screen:

7. Click on gateway (top left in the breadcrumbs) and you will be shown the Overview tab.
 OpenShift has now downloaded the code for the API gateway and has started a build to
construct it.
8. When the build completes, the UI will refresh and show two instances of the API gateway
(2 "pods") that have been started by OpenShift, as defined in the template.

Each instance of the 3scale API Gateway, upon starting, downloads the required
configuration files and code from 3scale using the configuration settings you provided on
the Integration tab of your 3scale Admin Portal.

OpenShift will maintain two gateway instances and monitor the health of both; an
unhealthy API gateway will automatically be replaced with a new one.

9. In order to allow your API gateways to receive traffic, you’ll need to create a route. Start by
clicking on Create route.
 In the Configure a host for the Origin Virtual Machine section, enter the hostname
you set in your /etc/hosts file in the Hostname field (e.g. gateway.openshift.demo) and
then click the Create button.

10. Your API gateways are now ready to receive traffic. OpenShift takes care of load-
balancing incoming requests to the route across the two running instances of the API
gateway.
 Test that the API gateway authorizes a valid call to your API, by executing a curl
command with the valid MY_USER_KEY that you noted down earlier:

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

11. Test it does not authorize an invalid call to your API

curl "http://gateway.openshift.demo/?user_key=[bad key value]"

You can access see the logs of API gateway traffic by clicking Browse > Pods and then
select one of the pods and then selecting Logs.

Success!!
Your API is now protected by two instances of the 3scale running on RedHat OpenShift, following
all the configuration that you set-up in the 3scale Admin Portal.

If you wish to shut down the OpenShift Origin VM to save resources, you can do so by opening
VirtualBox and right-clicking on the origin vm then selecting Close > ACPI Shutdown. You can
then close VirtualBox.

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

• Explore how to configure access policies for your API, and engage developers with a
Developer Portal by following the Quickstart
• Whenever you make changes to your API definition in the 3scale Admin Portal — in
particular the 3scale metrics/methods and mapping rules — you should create a new
deployment in OpenShift. This will start new instances that will download and run your
new API definition. Then OpenShift will shut down gracefully the previous instances.
• Run Openshift Enterprise V3 on your dedicated datacenter or on your favorite cloud
platform and then follow the same instructions to open up your API to the world.